📚 A minimal, read-only OPDS 1.2 server for existing Calibre libraries.
It is designed for containerized deployments where books are managed with Calibre but accessed through OPDS-compatible reader applications. The server provides catalog browsing and book acquisition without a web interface or library management features.
- OPDS 1.2 navigation, acquisition, and search feeds
- Browse books by newest, title, or author
- Download available book formats from OPDS-compatible readers
- Read-only access to existing Calibre libraries
- Multi-architecture Docker images for
amd64andarm64 - Liveness and readiness endpoints for container orchestration
Mount the root directory of an existing Calibre library. It must contain
metadata.db together with the author and book directories managed by Calibre.
The container accesses the library read-only and does not modify its contents.
docker run --rm -p 9000:8000 \
-v /path/to/calibre-library:/app/calibre:ro \
ghcr.io/victor1234/opds-server:0.1.3services:
opds-server:
image: ghcr.io/victor1234/opds-server:0.1.3
restart: unless-stopped
ports:
- 9000:8000
volumes:
- /path/to/calibre-library:/app/calibre:roVerify that the library is available:
curl http://<server-address>:9000/readyThen add http://<server-address>:9000/opds to your OPDS-compatible reader.
The server can be configured using environment variables:
| Variable | Default | Description |
|---|---|---|
PAGE_SIZE |
30 |
Number of books or authors shown on each OPDS feed page, from 1 through 100 |
OPDS_PREFIX |
/opds |
URL path where the catalog is mounted. A leading slash is optional; trailing slashes are removed |
The server starts when the configured library is temporarily unavailable so
that /healthz can continue to report process liveness. /ready checks the
library on every request and returns 503 Calibre database unavailable until
metadata.db can be accessed.
/healthz→ liveness probe (returns200if the server process is alive)/ready→ readiness probe (returns200if the Calibre database is available)