General

BookShelf is a self-hosted web application for managing your personal book library. It helps you organize books, track reading progress, and read ebooks—all from your own server.

Benefits of self-hosting:

  • Privacy - Your data stays on your server
  • Control - Customize features and appearance
  • No ads - Clean interface without distractions
  • Ebook reader - Read books directly in app
  • OPDS support - Connect your e-reader devices
  • Offline access - Works on your local network

You can still import from Goodreads and keep both!

Yes! BookShelf is open source and released under the MIT License. You only pay for hosting (your own server or cloud provider).

V2 is a complete rewrite with:

  • Modern tech stack (SvelteKit, TypeScript)
  • Better performance and UX
  • Smart Collections (Magic Shelves)
  • Enhanced ebook reader
  • Improved statistics and heatmap
  • Cleaner, more intuitive interface

V1 databases can be migrated to V2.

Installation & Setup

Minimal:

  • 512MB RAM
  • 1GB storage (plus space for ebooks)
  • Docker support (recommended)

Recommended:

  • 1GB+ RAM
  • 10GB+ storage
  • Linux server (Raspberry Pi 4 works great!)

Yes! BookShelf runs well on Raspberry Pi 3B+ or newer. Use the Docker image for easy setup.

No, you can access via:

  • http://localhost:3000 (local machine)
  • http://192.168.x.x:3000 (LAN IP)
  • Port forward for internet access (not recommended without HTTPS)

A domain makes setup cleaner but isn't required.

Use a reverse proxy like:

  • Nginx Proxy Manager (easiest, GUI-based)
  • Traefik (Docker-native)
  • Caddy (auto HTTPS with Let's Encrypt)

See Getting Started for examples.

Yes, options include:

  1. Port forwarding (with HTTPS!)
  2. VPN (Tailscale, WireGuard) - more secure
  3. Cloudflare Tunnel - no port forwarding needed
  4. Cloud hosting (DigitalOcean, AWS, etc.)
Don't expose port 3000 directly to internet without HTTPS!

Using BookShelf

Multiple ways:

  1. Manual entry - Fill out form
  2. ISBN lookup - Automatically fetch metadata
  3. CSV import - From Goodreads or spreadsheet
  4. Audible import - From library HTML export
  5. BookDrop - Drop ebook files in folder for auto-import

Yes! Export your Goodreads library as CSV, then use Import feature. Ratings, shelves (as tags), and read dates are preserved.

  • EPUB - Reflowable ebooks (best supported)
  • PDF - Documents and fixed-layout books
  • CBZ/CBR - Comic books and manga

Yes, via OPDS catalog! Most e-reader apps (Calibre, KOReader, Moon+ Reader, FBReader) support OPDS and can connect to your BookShelf.

Smart Collections (Magic Shelves) are dynamic - they auto-update based on rules you set.

Example: "5-Star Sci-Fi"

  • Genre = Science Fiction
  • Rating = 5 stars
  • Sort by: Date Read

Any book matching these conditions appears automatically.

Yes! BookShelf supports multiple users with separate libraries or a shared library. Admin users manage the system while members manage their books.

Yes, once loaded in browser. Reading ebooks works offline. Adding/editing books requires the server to be running.

Troubleshooting

Reset via command line:

# Docker
docker exec -it bookshelf npm run reset-password admin

# Manual installation
npm run reset-password admin

Enter new password when prompted.

Check:

  1. Import completed successfully (check notifications)
  2. No filters applied (clear all filters)
  3. Try different sort order
  4. Check Admin → Data Cleanup for issues

Possible causes:

  • Network issue (check internet connection)
  • API rate limits (wait and retry)
  • Provider is down (try different provider)
  • Invalid ISBN (verify ISBN is correct)

Solution: Admin → Settings → Metadata Providers - enable multiple providers. Try manual cover upload as fallback.

Check:

  1. File format is supported (EPUB, PDF, CBZ)
  2. File isn't corrupted (try opening in another app)
  3. File uploaded completely (check file size)
  4. Browser JavaScript is enabled

Try: Re-upload the file, try different browser, check browser console for errors.

Issue: Can't write files, database locked, etc.

Solution: Set PUID/PGID to match your user:

id -u  # Your UID
id -g  # Your GID

Update .env file:

PUID=1000
PGID=1000

Restart: docker compose restart

Migrations should run automatically. If not:

# Docker
docker exec -it bookshelf npm run db:migrate

# Manual
npm run db:migrate

If that fails:

  1. Restore from backup
  2. Check logs for specific error
  3. Report issue on GitHub

Features & Functionality

Yes! Set format to "Audiobook" and optionally add narrator. Reading time tracking works for time spent in app.

Yes! Multiple formats:

  • CSV - For spreadsheets or other apps
  • JSON - Complete backup with all metadata
  • Database file - SQLite file for direct access

Based on:

  1. Shared authors
  2. Same series
  3. Common genres
  4. Matching tags

AI recommendations (optional, requires OpenAI API key) provide more advanced suggestions.

Yes! Enable re-read counting in settings. Each completion is logged separately in reading history.

Not yet, but the web interface is fully responsive and works great on mobile browsers. Add to home screen for app-like experience!

Native iOS/Android apps are on the roadmap. OPDS support means your existing e-reader apps work now.

Data & Privacy

Everything is stored locally on your server:

  • Database: SQLite file in /data
  • Covers: /app/static/covers
  • Ebooks: /app/static/ebooks
  • Logs: /logs

Nothing is sent to external servers except:

  • Metadata lookups (when you explicitly fetch)
  • AI recommendations (if you enable OpenAI)

Only if you:

  1. Enable "Public Library" in settings
  2. Share OPDS catalog publicly
  3. Enable public widgets

By default, login is required.

Regularly:

  • Export → JSON backup (includes metadata)
  • Copy database file
  • Backup cover and ebook folders

Automated:

  • Set up cron job to backup database
  • Use Docker volume backups
  • Sync to cloud storage (Dropbox, Google Drive)

See Import & Export for scripts.

Yes! BookShelf is portable:

  1. Export JSON backup
  2. Copy ebook and cover folders
  3. Install BookShelf on new server
  4. Import JSON backup
  5. Copy ebook and cover folders to new location

Development & Contributing

Yes! BookShelf is open source. Contributions welcome:

  • Report bugs
  • Suggest features
  • Submit pull requests
  • Improve documentation
  • Translate to other languages

See CONTRIBUTING.md in the repository.

Open an issue on GitHub with:

  • BookShelf version
  • Environment (Docker, manual, OS)
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshots if applicable
  • Documentation: You're reading it!
  • GitHub Issues: For bugs and feature requests
  • GitHub Discussions: For questions and community help

Yes, MIT License allows commercial use. Attribution appreciated but not required.

Still Have Questions?

Ask on GitHub Discussions Report an Issue Read the User Guide