Docker Deployment Guide

This guide applies to all Docker-capable environments, including Linux, macOS, Windows, Synology, and QNAP.

Docker Compose is recommended. The image already includes the frontend, default database path, and internal service port. Most users only need to understand two settings:

• ports: exposes the container service port on the host and determines which port users visit.
• volumes: mounts the container data directory to host storage and determines whether data persists.

1. Quick Start

Create docker-compose.yml:

services:
  leelaa-reader:
    image: leedaisen/leelaa-reader-server:latest
    container_name: leelaa-reader
    ports:
      - "8686:8686"
    volumes:
      - ./data:/data
    environment:
      TZ: Asia/Shanghai
      # Optional: initial admin password. If omitted, one is generated and written to /data/password.txt.
      # DEFAULT_ADMIN_PASSWORD: set_a_strong_password
    restart: unless-stopped

Start:

docker compose up -d

Open:

http://SERVER_IP:8686

For local use:

http://localhost:8686

Check the generated initial password:

docker exec leelaa-reader cat /data/password.txt

Or check container logs:

docker logs leelaa-reader

2. ports

ports maps a host port to the container port:

ports:
  - "8686:8686"

Format:

HOST_PORT:CONTAINER_PORT

The container service port is 8686. Usually you only change the left side.

For example, if host port 8686 is already in use:

ports:
  - "18868:8686"

Then open:

http://SERVER_IP:18868

For Docker deployments, change the exposed access port through the left side of ports.

3. volumes

volumes configures data persistence:

volumes:
  - ./data:/data

Format:

HOST_PATH:CONTAINER_PATH

The container path /data stores Leelaa Reader runtime data:

• SQLite database
• initial admin password file password.txt
• cover cache
• runtime files

Always mount /data to host storage. Otherwise, deleting the container will lose the database and settings.

Relative path:

volumes:
  - ./data:/data

Absolute path:

volumes:
  - /volume1/docker/leelaa-reader/data:/data

Windows example:

volumes:
  - D:/docker/leelaa-reader/data:/data

To let the container read a host audiobook folder, add another mount:

volumes:
  - ./data:/data
  - /volume1/audiobooks:/books:ro

Then use this path in Leelaa Reader when adding a local library:

/books

:ro means read-only mount and is recommended for audiobook folders.

4. Optional Environment Variables

For normal deployments, only these variables are recommended:

Variable	Required	Description
TZ	No	Container timezone. Asia/Shanghai is recommended for China-based users.
DEFAULT_ADMIN_USERNAME	No	Initial admin username. Only takes effect when the database has no users; defaults to admin.
DEFAULT_ADMIN_PASSWORD	No	Initial admin password. Only takes effect when the database has no users; if omitted, a random password is generated and written to /data/password.txt.

Example:

environment:
  TZ: Asia/Shanghai
  DEFAULT_ADMIN_USERNAME: admin
  DEFAULT_ADMIN_PASSWORD: set_a_strong_password

After initial setup is complete, changing DEFAULT_ADMIN_USERNAME or DEFAULT_ADMIN_PASSWORD will not reset existing accounts.

5. Docker Run

If you do not use Compose:

docker run -d \
  --name leelaa-reader \
  -p 8686:8686 \
  -v ./data:/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  leedaisen/leelaa-reader-server:latest

To set the initial admin password:

docker run -d \
  --name leelaa-reader \
  -p 8686:8686 \
  -v ./data:/data \
  -e TZ=Asia/Shanghai \
  -e DEFAULT_ADMIN_PASSWORD=set_a_strong_password \
  --restart unless-stopped \
  leedaisen/leelaa-reader-server:latest

6. Image Architecture

The Docker image supports:

• linux/amd64: common x86_64 servers, Intel/AMD NAS devices, and PCs.
• linux/arm64: ARM64/aarch64 NAS devices, ARM servers, and Docker on Apple Silicon.

In most cases, use leedaisen/leelaa-reader-server:latest directly and Docker will pull the matching image automatically.

Check Docker server architecture:

docker version --format '{{.Server.Arch}}'

If logs show exec format error, the image architecture likely does not match the device architecture. You can set platform explicitly:

services:
  leelaa-reader:
    image: leedaisen/leelaa-reader-server:latest
    platform: linux/amd64
    container_name: leelaa-reader
    ports:
      - "8686:8686"
    volumes:
      - ./data:/data
    environment:
      TZ: Asia/Shanghai
    restart: unless-stopped

For ARM64/aarch64 devices:

platform: linux/arm64

7. Maintenance Commands

Check container status:

docker ps

Follow logs:

docker logs -f leelaa-reader

Stop service:

docker compose down

Upgrade image:

docker compose pull
docker compose up -d

Back up the host-side data directory before upgrading.

8. Troubleshooting

For page access issues, lost data after container removal, initial password lookup, local library paths, and architecture errors, see Docker Deployment Troubleshooting.