openreader/docs-site/docs/docker-quick-start.md

title
Docker Quick Start

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Prerequisites

• A recent Docker version installed
• A TTS API server that OpenReader can reach:
  • Kokoro-FastAPI
  • KittenTTS-FastAPI
  • Orpheus-FastAPI
  • Replicate
  • DeepInfra
  • OpenAI
  • Other OpenAI-compatible providers

:::warning 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. :::

1. Start the Docker container

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

What this command enables:

• -p 3003:3003: exposes the OpenReader web app/API.
• -p 8333:8333: exposes embedded SeaweedFS S3 endpoint for direct browser presigned upload/download.
• -v openreader_docstore:/app/docstore: persists SQLite metadata, SeaweedFS blob data, and migration/runtime state.
• -v /path/to/your/library:/app/docstore/library:ro: mounts a read-only importable library source.
• -e API_BASE=...: sets the server-side default TTS endpoint OpenReader calls.
• -e API_KEY=...: sets the server-side default TTS API key (none is fine for local backends that do not require auth).
• -e BASE_URL=... and -e AUTH_SECRET=...: together they turn on auth/session mode for local sign-in flows.

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.

What this command enables:

• LAN access from phones/tablets/other computers via http://<YOUR_LAN_IP>:3003.
• BASE_URL points auth/session cookies and callbacks at your LAN URL.
• AUTH_TRUSTED_ORIGINS allows localhost loopback origins in addition to your primary LAN origin.
• USE_ANONYMOUS_AUTH_SESSIONS=true allows guest sessions while auth is enabled.
• API_BASE still sets the default server-side TTS endpoint.
• openreader_docstore volume keeps data persistent across restarts.

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

What this command enables:

• Fastest startup with no extra env vars.
• No persistent volume (/app/docstore stays container-local), so data is ephemeral unless you add a mount.
• Auth remains disabled because BASE_URL and AUTH_SECRET are not set.
• TTS endpoint/key are not preset server-side (API_BASE/API_KEY not set), so configure provider settings in the app UI.

:::tip Quick Tips

• Set API_BASE to a TTS endpoint the container can reach (host.docker.internal works for host-local services).
• Auth is enabled only when both BASE_URL and AUTH_SECRET are set.
• Use a /app/docstore mount if you want data to survive container/image replacement.
• Startup automatically runs DB/storage migrations via the shared entrypoint. :::

:::warning 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. :::

2. Configure settings in the app UI

Visit http://localhost:3003 after startup.

• 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. :::

:::info Related Docs

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