Docker Quick Start

Prerequisites

• A recent Docker version installed
• A TTS API server that OpenReader can reach (Kokoro-FastAPI, KittenTTS-FastAPI, Orpheus-FastAPI, Replicate, DeepInfra, OpenAI, or equivalent)

SeaweedFS Compatibility Note (April 16, 2026)

OpenReader currently pins embedded SeaweedFS to 4.18 in CI and Docker builds. 4.19 introduced intermittent InternalError responses on S3 PutObject in our upload flow.

note

If you have suitable hardware, you can run Kokoro locally with Docker. See Kokoro-FastAPI.

1. Start the Docker container

Minimal

Auth disabled, embedded storage ephemeral, no library import:

docker run --name openreader \
  --restart unless-stopped \
  -p 3003:3003 \
  -p 8333:8333 \
  ghcr.io/richardr1126/openreader:latest

Localhost

Persistent storage, embedded SeaweedFS weed mini, optional auth, optional library mount:

docker run --name openreader \
  --restart unless-stopped \
  -p 3003:3003 \
  -p 8333:8333 \
  -v openreader_docstore:/app/docstore \
  -v /path/to/your/library:/app/docstore/library:ro \
  -e API_BASE=http://host.docker.internal:8880/v1 \
  -e API_KEY=none \
  -e BASE_URL=http://localhost:3003 \
  -e AUTH_SECRET=$(openssl rand -hex 32) \
  ghcr.io/richardr1126/openreader:latest

LAN Host

Use this when the app should be reachable from other devices on your LAN:

docker run --name openreader \
  --restart unless-stopped \
  -p 3003:3003 \
  -p 8333:8333 \
  -v openreader_docstore:/app/docstore \
  -e API_BASE=http://host.docker.internal:8880/v1 \
  -e BASE_URL=http://<YOUR_LAN_IP>:3003 \
  -e AUTH_SECRET=$(openssl rand -hex 32) \
  -e AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003 \
  -e USE_ANONYMOUS_AUTH_SESSIONS=true \
  ghcr.io/richardr1126/openreader:latest

Replace <YOUR_LAN_IP> with the Docker host IP address on your local network to allow access from other devices.

Quick Tips

• Remove /app/docstore/library if you do not need server library import.
• Remove either BASE_URL or AUTH_SECRET to keep auth disabled.
• Set API_BASE to your reachable TTS server base URL.

Port 8333 Exposure

Expose 8333 for direct browser presigned upload/download with embedded SeaweedFS.

If 8333 is not reachable from the browser, direct presigned access is unavailable. Uploads can still fall back to /api/documents/blob/upload/fallback, and document reads/downloads continue through /api/documents/blob.

Auth and Migrations

• Auth is enabled only when both BASE_URL and AUTH_SECRET are set.
• DB/storage migrations run automatically at container startup via the shared entrypoint.

Related Docs

• Environment Variables
• Auth
• Database
• Object / Blob Storage
• Migrations

2. Configure settings in the app UI

• Set TTS provider and model in Settings
• Set TTS API base URL and API key if needed
• Select the model voice from the voice dropdown

3. Update Docker image

Legacy image compatibility: ghcr.io/richardr1126/openreader-webui:latest remains available as an alias.

docker stop openreader || true && \
docker rm openreader || true && \
docker image rm ghcr.io/richardr1126/openreader:latest || true && \
docker pull ghcr.io/richardr1126/openreader:latest

tip

If you use a mounted volume for /app/docstore, your persisted data remains after image updates.

Visit http://localhost:3003 after startup.