Runary
A self-hosted personal book, audiobook, and comic manager with built-in readers, rich metadata support, device sync, and a 1900+ integration test suite.
Runary
A self-hosted personal book, audiobook, and comic manager with a built-in reader and rich metadata support. Available as a Docker image, fat JAR, or native binary.
Note: Runary is under active development. Core features are stable and covered by over 1900 integration tests. Test with a small library before committing your full collection.
What file formats can Runary read?
- EPUB — customisable fonts, themes, margins, RTL support, TOC sidebar
- PDF — in-browser viewing, text extraction, TOC from bookmarks
- Comic (CBZ/CBR) — double-page spread, continuous scroll, 5 fit modes, swipe gestures
- FB2 and DjVu
- Audiobook — multi-chapter playback, speed control, listening sessions
Cross-device position sync — resume on any device using EPUB CFI, PDF page number, or audio timestamp.
How does library management work?
- Multiple named libraries with folder-backed storage
- Batch import, bulk operations, auto-scan on configurable interval
- Smart shelves auto-populated by status, tag, or rating rules
- Filter presets for saved search configurations
- Custom metadata fields (text, number, date, select, boolean)
- ISBN barcode scanner via camera
- Duplicate detection with merge
- Full-text search in 30 languages with BM25 (PostgreSQL 17+)
- Calibre format conversion support
Where does Runary get metadata?
Fetch from OpenLibrary, Google Books, Hardcover, ComicVine, and Audible. Bulk refresh, metadata proposals for review, metadata locks to protect curated fields, alternative cover management.
What devices and services does Runary integrate with?
| Integration | Status |
|---|---|
| Kobo sync | Tested |
| KOReader (kosync) | Tested |
| OPDS 1.2 + 2.0 | Tested |
| OIDC / SSO (Keycloak) | Tested |
| Hardcover.app | Untested |
| Send-to-Kindle | Untested |
What reading analytics does Runary provide?
- Reading streaks, speed analytics, heatmaps, and goals
- Bookmarks and annotations with export to Markdown, JSON, and Readwise CSV
- Reading journals, notebooks, and reviews
- Whispersync — link an ebook and audiobook, switch seamlessly at the matching position
- Optional public reading profile
Quick Start
# docker-compose.yml
services:
runary:
image: ghcr.io/rygel/runary:latest
ports:
- "9999:9999"
environment:
RUNARY_JWT_SECRET: change-me-in-production
RUNARY_ENV: production
volumes:
- runary_data:/data
volumes:
runary_data:
docker compose up -d
# Open http://localhost:9999
Or run the fat JAR directly:
java -jar runary-v0.7.3.jar
Configuration
| Variable | Default | Description |
|---|---|---|
RUNARY_PORT | 9999 | HTTP port |
RUNARY_ENV | — | Set to production to enforce JWT secret |
RUNARY_JWT_SECRET | dev default | Change in production |
RUNARY_DB_URL | H2 file | JDBC URL — H2 (dev) or PostgreSQL (prod) |
RUNARY_BOOKS_PATH | ./data/books | Book file storage |
Tech Stack
Kotlin · HTTP4k · JTE · HTMX · JDBI 3 · Flyway · PostgreSQL / H2 · Koin · Caffeine · Maven
FAQ
What is Runary?
Runary is a self-hosted personal book, audiobook, and comic manager. It provides built-in readers for EPUB, PDF, CBZ/CBR, FB2, DjVu, and audiobooks, with metadata fetching from OpenLibrary, Google Books, Hardcover, ComicVine, and Audible. It runs as a Docker container, fat JAR, or native binary.
What file formats does Runary support?
EPUB, PDF, CBZ, CBR, FB2, and DjVu for ebooks and comics. MP3 and M4B for audiobooks. Calibre format conversion is supported for additional formats.
Does Runary sync reading position across devices?
Yes. Cross-device position sync works via EPUB CFI for ebooks, PDF page numbers, and audio timestamps. It also integrates with Kobo sync and the KOReader kosync protocol.
How do I install Runary?
The quickest way is Docker: pull ghcr.io/rygel/runary:latest and run with docker compose up -d. Alternatively, download the fat JAR or native binary from the GitHub Releases page.
What metadata sources does Runary use?
OpenLibrary, Google Books, Hardcover, ComicVine, and Audible. You can bulk-refresh metadata, review proposals before applying, and lock specific fields to protect curated data.
Does Runary require a specific database?
For development and small libraries, the embedded H2 database works out of the box. For production use with larger libraries and full-text search in 30 languages, PostgreSQL 17+ is recommended.