Skip to content

Docker_en

sensboston edited this page Nov 3, 2026 · 2 revisions

TinyOPDS in Docker (NAS)

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.

Step 1. Folders

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

Step 2. PUID and PGID

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.

Step 3. docker-compose.yml

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 /books and /data on the right. :ro makes the library read only.
  • If Docker Hub is not reachable, use ghcr.io/sensboston/tinyopds:latest as the image.

Installation

Synology DSM 7.2 and newer (Container Manager)

  1. Package Center → install Container Manager.
  2. Container Manager → Project → Create.
  3. Project name: tinyopds, path: the data folder (e.g. /docker/tinyopds).
  4. Source: Create docker-compose.yml → paste the text from step 3.
  5. 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.

Synology DSM 6 (Docker package)

DSM 6 has no projects (compose), so everything is set up in the dialogs:

  1. Docker → Registry → search for sensboston/tinyopds → Download → tag latest.
  2. Image → select sensboston/tinyopds → Launch → Advanced Settings.
  3. Enable auto-restart.
  4. Volume → Add Folder: the library → mount path /books, read only; the data folder → /data.
  5. Port Settings: local port 8080 (or another) → container port 8080.
  6. Environment → add PUID, PGID, TZ, TINYOPDS_LANGUAGE (values as in step 3).
  7. Apply → Next → Done.

QNAP (Container Station 3)

  1. App Center → install Container Station.
  2. Container Station → Applications → Create.
  3. Name: tinyopds, paste the text from step 3 (with /share/... paths and another port instead of 8080, e.g. "8090:8080").
  4. Create. The image is downloaded and the container starts.

CasaOS / ZimaOS

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.

Portainer

Stacks → Add stack → paste the text from step 3 → Deploy the stack.

Command line

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

First start and reader apps

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.

Password protection

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).

Other settings

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.

Book uploads

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.

Updates

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.

Database from a PC

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.

Clone this wiki locally