https://github.com/mishl-dev/shelfd
A self-hosted API that provides a unified interface for accessing ebooks. designed for integration with readers like Foliate.
https://github.com/mishl-dev/shelfd
ebook ebook-library foliate opds opds-catalog opds-server open-library open-library-api rust
Last synced: 29 days ago
JSON representation
A self-hosted API that provides a unified interface for accessing ebooks. designed for integration with readers like Foliate.
- Host: GitHub
- URL: https://github.com/mishl-dev/shelfd
- Owner: mishl-dev
- License: mit
- Created: 2026-03-17T18:50:42.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-26T11:15:42.000Z (3 months ago)
- Last Synced: 2026-03-27T04:27:34.092Z (3 months ago)
- Topics: ebook, ebook-library, foliate, opds, opds-catalog, opds-server, open-library, open-library-api, rust
- Language: Rust
- Homepage:
- Size: 329 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
shelfd
A small self-hosted OPDS server for ebook archives.
Browse by subject, search from reader apps, and fill in covers and metadata automatically.
## What It Does
- turns an ebook archive into an OPDS catalog
- gives you an explore-first browsing feed instead of search-only UX
- still supports OPDS search for clients like Foliate
- pulls metadata and covers from Open Library when available
- generates fallback covers when nothing better exists
## Quick Start
Run with `just`:
```bash
just up
```
Or without `just`:
```bash
docker compose up --build
```
Then open:
- `http://localhost:7451/opds`
Stop:
```bash
just down
```
Or:
```bash
docker compose down
```
Config
The defaults are enough to get started, but these are the settings you will most likely care about:
- `ARCHIVE_URLS`: comma-separated archive base URLs for round-robin racing
- `ARCHIVE_BASE`: fallback single archive URL (used if `ARCHIVE_URLS` is not set)
- `ARCHIVE_NAME`: display name shown in feeds
- `APP_NAME`: app name shown to OPDS clients
- `PUBLIC_BASE_URL`: public base URL for generated links
- `DATABASE_URL`: SQLite database location
- `RUST_LOG`: log level and filters
Endpoints
- `GET /opds`
- `GET /opds/search?q=...`
- `GET /healthz`
Dev
```bash
just up
just test
just lint
just fmt
```
## License
MIT. See [LICENSE](LICENSE).