BookLore: A Self-Hosted Library That Reads, Syncs and Organizes Your Books

What BookLore solves, and who ends up running it

Most people with a few thousand ebooks end up with three problems at once. The files sit in a folder tree that only makes sense to the person who built it. The metadata lives in whichever tool last touched the file. And reading progress is scattered across a phone, a Kobo and a desktop PDF viewer that never talk to each other. BookLore is aimed squarely at that situation. It presents itself as a self-hosted app that brings a collection under one roof: organize, read, annotate, sync across devices, and share, without relying on third-party services.

The audience is narrower than "anyone with ebooks." BookLore is a server application. The README's Quick Start assumes Docker and Docker Compose, and the compose file it gives you runs two containers: the application and MariaDB. If you want a desktop program that opens a file when you double-click it, this is the wrong shape entirely. If you want one address on your network where every household member has their own shelves, progress and preferences, and where a Kobo or a KOReader install can pull from the same source, that is the design target. Multi-user support is explicit: individual shelves, progress and preferences per user with local or OIDC authentication.

Spring Boot, Angular and MariaDB: how the pieces fit

The repository is split into booklore-api and booklore-ui, and the Dockerfile shows exactly how they are joined. Stage one builds the Angular app with Node 24 and runs npm run build --configuration=production. Stage two builds the Spring Boot service with Gradle 9.3.1 on JDK 25, then copies the Angular output from /angular-app/dist/booklore/browser into /springboot-app/src/main/resources/static. The result is a single JAR with the frontend embedded, and stage three is the runtime image on eclipse-temurin:25-jre-alpine.

That layout matters for anyone thinking about deployment. There is no separate web server and no reverse proxy required in the default setup. One process serves the API and the interface on port 6060. Persistence is external: the compose file points the app at a MariaDB instance through DATABASE_URL, and the database container is lscr.io/linuxserver/mariadb:11.4.5. The application container declares depends_on with condition: service_healthy, so the app waits for MariaDB's mariadb-admin ping healthcheck before starting. The app's own healthcheck hits http://localhost:6060/api/v1/healthcheck.

File handling is the part worth reading twice. The README states that BookLore's file operations, meaning metadata writing, file renaming and file organization, are built for local file systems only. A DISK_TYPE variable switches between LOCAL and NETWORK. In NETWORK mode, all file write and reorganization features are disabled, metadata is stored in the database only, and the files are never modified. That is a deliberate trade: you keep the catalog and lose the automatic file management.

Installing BookLore with Docker Compose

The README's Quick Start needs Docker and Docker Compose and nothing else. The image is published to GitHub Container Registry as ghcr.io/booklore-app/booklore. First create a .env file. The values below are the README's own example; the two passwords are placeholders and should be changed before the stack is exposed to anything.

APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC
DATABASE_URL=jdbc:mariadb://mariadb:3306/booklore
DB_USER=booklore
DB_PASSWORD=ChangeMe_BookLoreApp_2025!
DISK_TYPE=LOCAL
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025!
MYSQL_DATABASE=booklore

Next, the compose file. It declares the booklore service, the mariadb service, and three volumes: ./data for application state, ./books for the library, and ./bookdrop for the import folder.

services:
  booklore:
    image: ghcr.io/booklore-app/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
    restart: unless-stopped

Bring it up, then open the address in a browser. The README says to create your admin account at that point and start building the library.

docker compose up -d

After the containers report healthy, http://localhost:6060 should show the setup screen. The first real use is the BookDrop folder. With ./bookdrop mounted, the documentation says BookLore monitors that folder around the clock, detects new files, fetches metadata from Google Books and Open Library, and queues them for review before they enter the library. Copy a few EPUBs into ./bookdrop and they should appear as pending imports rather than landing silently in the catalog.

Where BookLore breaks: network storage and the write path

The README is unusually blunt about one failure mode, and it deserves repeating rather than paraphrasing. File operations are built for local file systems only. Network-attached storage, including NAS, NFS, SMB/CIFS mounts and cloud-backed FUSE, is described as unsupported and untested. The stated risks are silent file corruption, incomplete writes, missing files and other unpredictable behavior, and the project says issues related to network storage will be closed without investigation.

That is a policy as much as a technical limitation, and it should shape how you plan a deployment. The escape hatch is DISK_TYPE=NETWORK, which disables all file write and reorganization features and keeps metadata in the database only. You still get the catalog, the reader and the sync endpoints, but BookLore stops touching your files. If your collection lives on a NAS share and you were hoping for automatic renaming and metadata embedding, the supported configuration does not give you that.

A second constraint is less dramatic but real: the default stack is two stateful containers. MariaDB is a dependency, not an option, and the database volume is separate from the books volume. Backups have to cover both. The README does not document a rollback procedure or a downgrade path between releases, so pinning a version tag rather than :latest is the only lever the documentation actually offers.

BookLore vs Calibre, and where the OPDS and Kobo sync sit

The comparison people reach for is Calibre, and the difference is architectural rather than cosmetic. Calibre is a desktop application that manages a local library folder and writes metadata into it. BookLore is a server with a database. Metadata edits go to MariaDB, and in LOCAL mode they may also be written to files; in NETWORK mode they stay in the database. That means a Calibre library is portable by copying a directory, while a BookLore instance is portable by dumping a database and copying ./books.

What BookLore adds on top is the sync surface. The README lists Kobo connection, OPDS support for any compatible app, and KOReader progress sync. Those are the features a desktop library manager does not have, and they are the reason to accept the extra container. If you only ever read on one machine and never leave the house with a device, Calibre's model is simpler and has no server to keep patched.

The honest limit on this comparison is that the README does not document how the Kobo sync is configured, which OPDS endpoints are exposed, or how KOReader authentication works. Those details are not in the README, and anyone whose decision hinges on them should read the docs/ directory in the repository before committing.

Licence, maintenance and the cost of upgrading

BookLore is licensed under the GNU Affero General Public License v3.0, copyright 2024 to 2026. The AGPL matters more for a self-hosted tool than it first appears. Running it on your own hardware for your own library does not trigger the network-use clause in any way that concerns an ordinary user. If you modify BookLore and offer it to others over a network, the AGPL's source-availability requirement is the part to read carefully. That is a description of the licence, not legal advice.

The repository is not archived, and the last push to the develop branch was on 2026-09-10. Recent tagged releases are v2.3.1 on 2026-06-26, v2.3.0 on 2026-04-29 and v2.2.2 on 2026-04-14. Note the gap between the last tag and the last push: work continues on develop between releases, so running a tag and running the branch are different propositions.

Upgrade cost is dominated by the database. The compose example uses image: ghcr.io/booklore-app/booklore:latest, which means a docker compose pull followed by docker compose up -d will move you to whatever was published most recently. The README does not describe schema migration steps or a supported downgrade path. If you want a predictable upgrade, replace :latest with a specific tag and read the release notes before moving.

Editorial conclusion

Adopt BookLore if your books live on a local disk, you want a browser reader plus Kobo, KOReader or OPDS sync, and you accept a MariaDB-backed stack on port 6060. Skip it if your library sits on NAS, NFS or SMB mounts, because the README treats network storage as unsupported and closes those issues without investigation. Before committing, verify that ./data, ./books and ./bookdrop resolve to local paths on the host, that DISK_TYPE matches that reality, and that you have changed the two placeholder passwords in the .env file.

Frequently asked questions

Official sources

1. booklore-app/booklore on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases