Repository navigation
Docker_en
TinyOPDS CLI is available as a Docker image for NAS (Synology, QNAP, etc.) and any Linux host with Docker, for amd64 (Intel/AMD) and arm64 processors. It is the same server as on Windows: OPDS catalog, web interface with the built-in reader, search, conversion to EPUB and MOBI, just without the window — everything is set up by the container settings.
Image: sensboston/tinyopds on Docker Hub, also published as ghcr.io/sensboston/tinyopds (use it if Docker Hub is not reachable).
Beta. What was tested and what was not. The author doesn't own a NAS, so the image was not tested on real Synology, QNAP or other NAS hardware. Every build passes automated tests on Linux amd64 and arm64 (scan, search, duplicates, downloads, web interface, data folder permissions, folder watcher, passwords), and the image was installed and tested in the CasaOS demo. If you run it on a NAS, please open an issue or post in the forum thread: NAS model, OS version, number of books, first scan time and, if something goes wrong, the container log.
Two folders are needed:
- library — your books: FB2, EPUB, ZIP archives (Flibusta, Librusec distributions included), subfolders are fine. TinyOPDS only reads it;
-
data folder — TinyOPDS keeps its settings (
TinyOPDS.config), database (books.sqlite) and log here. Keep it: with it the library is not rescanned from scratch after an image update.
Example paths (use your own):
| System | Library | Data folder |
|---|---|---|
| Synology | /volume1/books |
/volume1/docker/tinyopds (create docker and tinyopds in File Station) |
| QNAP | /share/Books |
/share/Container/tinyopds |
| CasaOS / ZimaOS | /DATA/Media/Books |
/DATA/AppData/tinyopds |
The server runs as the NAS user given by PUID (user ID) and PGID (group ID), so files in the data folder belong to that user, not to root. To find them, log in to the NAS with SSH as that user and run
id
An answer like uid=1026(user) gid=100(users) means PUID=1026, PGID=100. On Synology the first created user usually has exactly 1026 and 100. The user needs read access to the library and write access to the data folder.
The same text is used by all the installation methods below. Change the folders on the left side of volumes, PUID/PGID and, if needed, the port.
services:
tinyopds:
image: sensboston/tinyopds:latest
container_name: tinyopds
ports:
- "8080:8080"
volumes:
- /volume1/books:/books:ro
- /volume1/docker/tinyopds:/data
environment:
- PUID=1026
- PGID=100
- TZ=Europe/London
- TINYOPDS_LANGUAGE=en
restart: unless-stopped-
ports: the left number is the port on the NAS, keep the right one (8080). If 8080 is taken, use e.g."8090:8080". On QNAP port 8080 is used by the QTS web interface by default, so choose another one right away. -
volumes: your folders on the left, keep/booksand/dataon the right.:romakes the library read only. - If Docker Hub is not reachable, use
ghcr.io/sensboston/tinyopds:latestas the image.
- Package Center → install Container Manager.
- Container Manager → Project → Create.
- Project name:
tinyopds, path: the data folder (e.g./docker/tinyopds). - Source: Create docker-compose.yml → paste the text from step 3.
- Next → (Web Station settings can be skipped) → Done. The image is downloaded and the container starts.
If DSM warns about the firewall, allow the chosen port.
DSM 6 has no projects (compose), so everything is set up in the dialogs:
- Docker → Registry → search for
sensboston/tinyopds→ Download → taglatest. -
Image → select
sensboston/tinyopds→ Launch → Advanced Settings. - Enable auto-restart.
-
Volume → Add Folder: the library → mount path
/books, read only; the data folder →/data. - Port Settings: local port 8080 (or another) → container port 8080.
-
Environment → add
PUID,PGID,TZ,TINYOPDS_LANGUAGE(values as in step 3). - Apply → Next → Done.
- App Center → install Container Station.
- Container Station → Applications → Create.
- Name:
tinyopds, paste the text from step 3 (with/share/...paths and another port instead of 8080, e.g."8090:8080"). - Create. The image is downloaded and the container starts.
On the main screen "+" → Install a customized app → import icon at the top right → Docker Compose tab → paste the text from step 3 with this block added at the end (icon and title in CasaOS) → Submit → Install.
x-casaos:
main: tinyopds
title:
en_us: TinyOPDS
icon: https://raw.githubusercontent.com/sensboston/tinyopds/master/TinyOPDS/TinyOPDS.png
port_map: "8080"port_map is the same port as the left side of ports.
Stacks → Add stack → paste the text from step 3 → Deploy the stack.
In the folder with docker-compose.yml:
sudo docker compose up -d
or without a compose file:
sudo docker run -d --name tinyopds -p 8080:8080 \
-v /volume1/books:/books:ro -v /volume1/docker/tinyopds:/data \
-e PUID=1026 -e PGID=100 -e TZ=Europe/London -e TINYOPDS_LANGUAGE=en \
--restart unless-stopped sensboston/tinyopds:latest
The container scans the library on every start: the first time it indexes all books, then only new ones. The server works while scanning, books appear as they are processed. The scan progress is shown in the container log (a line every 30 seconds).
How long the first scan takes on a NAS is not known yet: on a PC the Flibusta library (about 600,000 books) takes a couple of hours, a NAS with a Celeron/N100 and hard disks will be slower, an ARM NAS slower still. Please report your time.
Then:
- web interface:
http://<NAS address>:8080/ - OPDS catalog for reader apps (KOReader, Moon+ Reader, FBReader, PocketBook, etc.):
http://<NAS address>:8080/opds
(replace 8080 with your port if you changed it)
New books: just copy them to the library folder; about 30 seconds after copying is over they appear by themselves, no restart is needed. Deleted and renamed files are processed too. If the library is on a network share of another computer (the folder watcher doesn't see changes there), the library is fully rescanned once a day.
Get the encrypted user list (one or more user/password pairs) with SSH on the NAS:
sudo docker run --rm sensboston/tinyopds encred user1 password1 user2 password2
and add two lines to environment:
- TINYOPDS_USEHTTPAUTH=true
- TINYOPDS_CREDENTIALS=<the printed line>Then recreate the container (Container Manager: project → Action → Build; QNAP: application → Update; command line: sudo docker compose up -d).
Any setting of TinyOPDS.config can be given as an environment variable TINYOPDS_<SETTING NAME> in upper case. Useful ones:
| Variable | Default | Meaning |
|---|---|---|
TINYOPDS_LANGUAGE |
en |
Interface and web site language: en, ru, uk, de, fr, es, pl
|
TINYOPDS_SERVERNAME |
Library name | |
TINYOPDS_DARKTHEMEONWEB |
false |
Dark theme of the web interface |
TINYOPDS_ROOTPREFIX |
opds |
OPDS catalog path |
TINYOPDS_ITEMSPEROPDSPAGE |
100 |
Items per OPDS page |
TINYOPDS_WATCHLIBRARY |
true |
Watch the library folder for new, renamed and deleted books |
TINYOPDS_SCAN_INTERVAL_HOURS |
24 |
Full rescan interval in hours, 0 switches it off |
TZ |
UTC |
Time zone, e.g. Europe/London
|
/data/TinyOPDS.config can also be edited directly, but only while the container is stopped; environment variables take precedence over the file.
To add books from the web interface (see Book uploads), add TINYOPDS_ENABLEUPLOADS=true (and TINYOPDS_MAXUPLOADSIZEMB for a size limit other than 20 MB) to environment and remove :ro from the library folder: uploaded books are saved to its Uploads subfolder, so the PUID user needs write access to the library.
Download the new image and recreate the container:
- Synology DSM 7: Container Manager shows that an update is available; or project → Action → Stop, Image → update, project → Build;
- QNAP: application → Update;
- command line:
sudo docker compose pull && sudo docker compose up -d.
The database and settings in the data folder are kept. Some releases ask to rescan the library from scratch, see the release notes.
A large library can be scanned by TinyOPDS on Windows (faster) and books.sqlite copied to the data folder on the NAS. The archives must be in the root of the library folder both on the PC and on the NAS (book paths are stored relative to that folder). Stop the container while copying.