Your books deserve a home. This is it.

BookLore is a self-hosted app that brings your entire book collection under one roof.
Organize, read, annotate, sync across devices, and share, all without relying on third-party services.

---

✨ Features

	Feature	Description
📚	Smart Shelves	Custom and dynamic shelves that organize themselves with rule-based Magic Shelves, filters, and full-text search
🔍	Automatic Metadata	Covers, descriptions, reviews, and ratings pulled from Google Books, Open Library, and Amazon, all editable
📖	Built-in Reader	Open PDFs, EPUBs, and comics right in the browser with annotations, highlights, and reading progress
🔄	Device Sync	Connect your Kobo, use any OPDS-compatible app, or sync progress with KOReader. Your library follows you everywhere
👥	Multi-User Ready	Individual shelves, progress, and preferences per user with local or OIDC authentication
📥	BookDrop	Drop files into a watched folder and BookLore detects, enriches, and queues them for import automatically
📧	One-Click Sharing	Send any book to a Kindle, an email address, or a friend instantly

---

🚀 Quick Start

All you need is Docker and Docker Compose.

📦 Image Repositories

Registry	Image
GitHub Container Registry	ghcr.io/imnotjames/booklore

Step 1: Environment Configuration

Create a .env file:

# Application
APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC

# Database
DATABASE_URL=jdbc:mariadb://mariadb:3306/booklore
DB_USER=booklore
DB_PASSWORD=ChangeMe_BookLoreApp_2025!

# Storage: LOCAL (default) or NETWORK (disables file operations, see Network Storage section below)
DISK_TYPE=LOCAL

# MariaDB
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025!
MYSQL_DATABASE=booklore

Step 2: Docker Compose

Create a docker-compose.yml:

services:
  booklore:
    image: ghcr.io/imnotjames/booklore:latest
    container_name: booklore
    environment:
      - USER_ID=${APP_USER_ID}
      - GROUP_ID=${APP_GROUP_ID}
      - TZ=${TZ}
      - DATABASE_URL=${DATABASE_URL}
      - DATABASE_USERNAME=${DB_USER}
      - DATABASE_PASSWORD=${DB_PASSWORD}
      - DISK_TYPE=${DISK_TYPE}
    depends_on:
      mariadb:
        condition: service_healthy
    ports:
      - "6060:6060"
    volumes:
      - ./data:/app/data
      - ./books:/books
      - ./bookdrop:/bookdrop
    healthcheck:
      test: wget -q -O - http://localhost:6060/api/v1/healthcheck
      interval: 60s
      retries: 5
      start_period: 60s
      timeout: 10s
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:11.4.5
    container_name: mariadb
    environment:
      - PUID=${DB_USER_ID}
      - PGID=${DB_GROUP_ID}
      - TZ=${TZ}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${DB_USER}
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./mariadb/config:/config
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "mariadb-admin", "ping", "-h", "localhost" ]
      interval: 5s
      timeout: 5s
      retries: 10

Step 3: Launch

docker compose up -d

Open http://localhost:6060, create your admin account, and start building your library.

---

⚠️ Network Storage (NAS / NFS / SMB / CIFS)

Caution

BookLore's file operations (metadata writing, file renaming, file organization) are built for local file systems only. Network-attached storage (NAS, NFS, SMB/CIFS mounts, cloud-backed FUSE, etc.) is unsupported and untested. Mount options, network latency, caching, and filesystem semantics are all outside BookLore's control and can cause silent file corruption, incomplete writes, missing files, and other unpredictable behavior. Issues related to network storage will be closed without investigation.

If your book files live on network storage, set DISK_TYPE=NETWORK in your .env file. This puts BookLore into network storage mode, which disables all file write and reorganization features. Metadata is stored in the database only and your files are never modified. This is the only supported configuration for network storage.

---

📥 BookDrop: Zero-Effort Import

Drop book files into a folder. BookLore picks them up, pulls metadata, and queues everything for your review.

graph LR
    A[📁 Drop Files] --> B[🔍 Auto-Detect]
    B --> C[📊 Extract Metadata]
    C --> D[✅ Review & Import]

Loading

Step	What Happens
1. Watch	BookLore monitors the BookDrop folder around the clock
2. Detect	New files are picked up and parsed automatically
3. Enrich	Metadata is fetched from Google Books and Open Library
4. Import	You review, tweak if needed, and add to your library

Mount the volume in docker-compose.yml:

volumes:
  - ./bookdrop:/bookdrop

---

🤝 Community & Support

🐞 Something not working?	Report a Bug
💡 Got an idea?	Request a Feature
🛠️ Want to help build?	Contributing Guide

Warning

Before opening a PR: Open an issue first and get maintainer approval. PRs without a linked issue, without screenshots/video proof, or without pasted test output will be closed. All code must follow project backend and frontend conventions. AI-assisted contributions are welcome, but you must run, test, and understand every line you submit. See the Contributing Guide for full details.

---

👥 Contributors

Every contribution matters. See how you can help →

---

⚠️ Note to Integrators

While BookLore is open source and its API is accessible, it is not designed or maintained as a stable integration point. Endpoints are undocumented, unversioned, and may change or break at any time without notice. No compatibility guarantees or support are provided for third-party use.

⚖️ License

GNU Affero General Public License v3.0