bookorbit README

The project's README from github.com/bookorbit/bookorbit. As one markdown file: README.md.

BookOrbit

A self-hosted library and reading platform for ebooks, PDFs, audiobooks, and comics.

Latest release Stars CI Release Coverage Crowdin

Website Demo GHCR Pulls Contributing License: AGPL v3

BookOrbit dashboard showing reading stats, widgets, and book shelves

What is BookOrbit?

BookOrbit organizes your books and reads them back to you anywhere: the web reader, a Kobo, or KOReader. Progress, highlights, and reading status move between all three, so you can start a chapter in one place and finish it in another.

Around that core sit 14 metadata providers, reading statistics and achievements, OPDS and Send-to-Kindle delivery, multi-user accounts with OIDC/SSO, and automatic sync out to Hardcover, Readwise, and StoryGraph. All of it runs on infrastructure you control.

Visit Website

Live Demo

Try the live instance before you install. No account required.

Launch Live Demo

Note: The demo includes a sample library of public domain books. Some administrative features are limited in the public demo. Self-hosting BookOrbit provides the full experience.

Features

Reading Experience & Sync

Library Management

Platform & Delivery

Quick Start (Docker)

mkdir bookorbit && cd bookorbit
mkdir -p books data/app data/postgres
curl -fsSLo .env https://raw.githubusercontent.com/bookorbit/bookorbit/main/.env.example
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/bookorbit/bookorbit/main/docker-compose.yml

Edit .env and set these required values:

APP_URL=http://your-server-ip:3000   # the URL you'll open in your browser
BOOKS_HOST_PATH=./books              # folder on your server where your book files live

POSTGRES_PASSWORD=         # database password           - openssl rand -hex 24
JWT_SECRET=                # signs login tokens          - openssl rand -hex 32
SETUP_BOOTSTRAP_TOKEN=     # one-time setup wizard token - openssl rand -hex 16

On a NAS, or any host where your book folder is owned by a user other than UID 1000, also set PUID and PGID to match that owner. Run id -u and id -g as the owning user to find them. Getting these wrong is the most common cause of permission errors on first scan.

Optionally set LIBRARY_BROWSE_ROOT=/books to start the library folder picker at /books instead of /.

Then start:

docker compose up -d

Open http://your-server-ip:3000 and complete setup using your SETUP_BOOTSTRAP_TOKEN.

After configuring OIDC and linking at least one active administrator, you can set DISABLE_LOCAL_AUTH=true and restart BookOrbit to remove and reject password sign-in. BookOrbit refuses to start if that would leave no usable OIDC administrator. Set it back to false and restart to recover access during an identity-provider outage.

For the full installation guide including reverse proxy setup, file permissions on NAS, external databases, and environment variable reference, see bookorbit.app/installation.

KOReader Plugin

The BookOrbit plugin for KOReader adds progress sync, two-way annotation sync, and a native catalog browser: navigate, search, and download books from your library without leaving the device.

BookOrbit KOReader Plugin showing dashboard, catalog search, and book details

  1. In BookOrbit, go to Settings > KOReader, create credentials if prompted, and click Download Plugin.
  2. Unzip bookorbit.koplugin.zip.
  3. Copy bookorbit.koplugin to koreader/plugins/ on the device.
  4. Restart KOReader and open a book.
  5. Use Tools > BookOrbit Sync to connect.

The download is pre-configured with your server URL and credentials, so there is no manual entry on the device. For full setup and sync options, see bookorbit.app/koreader-plugin.

Documentation and Contributing

Full documentation is at bookorbit.app, covering libraries, metadata, readers, Kobo sync, OPDS, users and permissions, OIDC setup, and more.

For setting up book requests, see the book requests guide: indexers, download clients, path mappings, automation, and the encryption key they all need. For local development, see docs/DEVELOPMENT.md. To contribute, see docs/CONTRIBUTING.md for the full workflow: branch naming, test expectations, PR checklist, and commit format.

Repository Activity

BookOrbit repository activity: commits, issues, and pull requests over the last 30 days

Translations

Help translate BookOrbit into your language on Crowdin.

When adding user-facing text in code, add the Vue I18n key only to client/src/locales/en.json. Do not edit non-English catalogs in a feature pull request; untranslated keys fall back to English until Crowdin provides a translation. See docs/LOCALIZATION.md for the complete workflow.

Translation progress

Star History

BookOrbit GitHub star history

Support

License

BookOrbit is licensed under the GNU Affero General Public License v3.0.

bookorbit (bookorbit/bookorbit)

Searching Database…

5.4K ·GitHub
Bookorbit
Что это такое?BookOrbit — это самостоятельно размещаемая библиотека и платформа для чтения электронных книг, PDF, аудиокниг и комиксов со встроенными веб-читалками и синхронизацией между устройствами.
Это отдельный сервер или то, что добавляется в существующее приложение?Это отдельное серверное приложение для самостоятельного размещения (на основе Docker) со своим веб-клиентом и сервером, написанное на NestJS и Vue.
Как это запустить?Заполните файл .env нужными значениями, запустите через Docker Compose, затем откройте приложение и завершите настройку, используя SETUPBOOTSTRAPTOKEN.
Нужно ли что-то особенное, например совпадающие ID пользователя и группы на NAS?На NAS или любом хосте, где папка с книгами принадлежит не UID 1000, нужно задать PUID и PGID, равные владельцу папки; их можно узнать командами id -u и id -g.
Какой самый серьёзный подвох при установке?Неверно заданные PUID/PGID — самая частая причина ошибок доступа при первом сканировании библиотеки. Также отключение локальной аутентификации без работающей привязки OIDC-администратора заблокирует доступ (в таком случае BookOrbit отказывается запускаться).
Может ли несколько человек использовать один экземпляр BookOrbit?Да, поддерживаются аккаунты для нескольких пользователей с детальными правами для каждого и изолированными данными чтения, а также встроенная поддержка OIDC/SSO через Authentik, Keycloak и Authelia.
Остаются ли мои данные на инфраструктуре, которую я контролирую?Да, всё — включая провайдеров метаданных, синхронизацию и учётные записи пользователей — работает на инфраструктуре, которую вы контролируете, так как приложение полностью самостоятельно размещается.
Как работает синхронизация между моим Kobo, KOReader и веб-читалкой?Прогресс и аннотации передаются в обоих направлениях между устройствами Kobo, KOReader и веб-читалкой BookOrbit, поэтому выделения, удаления и прогресс чтения объединяются во всех трёх.
Какие форматы файлов BookOrbit действительно умеет читать?Встроенные читалки поддерживают электронные книги в форматах EPUB, KEPUB, MOBI, AZW3, AZW, FB2, PDF, комиксы CBZ/CBR/CB7 и аудиокниги M4B/MP3/M4A/OPUS/OGG/FLAC, без дополнительных плагинов.
Умеет ли приложение подтягивать метаданные и синхронизировать мою статистику чтения с другими сервисами?Да, оно получает метаданные от 14 провайдеров (Google Books, Goodreads, Audible и др.) и может передавать статус, прогресс и оценки в Hardcover, Readwise и The StoryGraph.
Что такое Book Dock?Это настраиваемая папка-приёмник для автоматического, без ручных действий, добавления книг в библиотеку.
What are similar projects?bookshelf, readest, calibre-web, grimmory, Kavita, audiobookshelf, koreader, overleaf
Which topics is it in?opds, nestjs, ebook-reader, epub, sso, oauth2, multilingual, agpl, pdf, vue, cloud, server
Creator
bookorbit
Size
117.2 MB
Stars
5.4K
Updated
CommitOct 17Releasev3.4.0Oct 13
Age
5mo
Commits · 90 Days