openreader/docs-site/docs/deploy/local-development.md

title
Local Development

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

Prerequisites

Node.js + pnpm (required)

brew install nvm pnpm
mkdir -p ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$(brew --prefix nvm)/nvm.sh" ] && . "$(brew --prefix nvm)/nvm.sh"' >> ~/.zshrc
source ~/.zshrc
nvm install --lts
nvm use --lts
node -v
pnpm -v

# Debian/Ubuntu example
sudo apt update
sudo apt install -y curl
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install --lts
nvm use --lts
corepack enable
corepack prepare pnpm@latest --activate
node -v
pnpm -v

SeaweedFS weed binary (required unless using external S3)

brew install seaweedfs
weed version

:::warning SeaweedFS Compatibility Note (April 16, 2026) If you see intermittent S3 InternalError upload failures with embedded storage, use SeaweedFS 4.18. OpenReader currently pins 4.18 in CI and Docker builds while 4.19 compatibility is investigated. :::

# Linux amd64 example (pin 4.18)
mkdir -p "$HOME/.local/bin"
curl -fsSL -o /tmp/seaweedfs.tar.gz \
  https://github.com/seaweedfs/seaweedfs/releases/download/4.18/linux_amd64.tar.gz
tar -xzf /tmp/seaweedfs.tar.gz -C /tmp weed
install -m 0755 /tmp/weed "$HOME/.local/bin/weed"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"
weed version

:::warning SeaweedFS Compatibility Note (April 16, 2026) If you see intermittent S3 InternalError upload failures with embedded storage, use SeaweedFS 4.18. OpenReader currently pins 4.18 in CI and Docker builds while 4.19 compatibility is investigated. :::

LibreOffice (optional, for DOCX conversion)

brew install libreoffice

# Debian/Ubuntu example
sudo apt update
sudo apt install -y libreoffice

Word-by-word highlighting (optional)

No extra native Whisper CLI build step is required.

Set COMPUTE_MODE=local to enable built-in ONNX word alignment in-process.

If you need mirrors or pinned artifact locations, set WHISPER_MODEL_BASE_URL in .env.

External compute worker dev stack (optional)

Use this when you want durable compute with NATS JetStream + KV while keeping Next.js on native host pnpm dev. Full worker deployment details are in Compute Worker (NATS JetStream).

Start only NATS + compute-worker via compose watch:

docker compose --env-file compute/worker/.env -f compute/worker/docker-compose.yml up --watch
# or: pnpm compute:dev:watch

compute/worker/.env.example contains a starter config. Copy it to compute/worker/.env and adjust values for your environment.

Run the main app separately on the host:

pnpm dev

For app server worker mode, set:

COMPUTE_MODE=worker
COMPUTE_WORKER_URL=http://localhost:8081
COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>

Worker mode requires worker-reachable shared object storage (S3-compatible endpoint). Non-exposed embedded weed mini is not a supported topology for external worker mode.

Steps

Required flow

1. Clone the repository.

git clone https://github.com/richardr1126/openreader.git
cd openreader

2. Install dependencies.

pnpm i

3. Configure the environment.

cp .env.example .env

Then edit .env.

Use one of these .env mode templates:

API_BASE=http://host.docker.internal:8880/v1
API_KEY=none
COMPUTE_MODE=local
# Leave BASE_URL and AUTH_SECRET unset to keep auth disabled.
# (Admin panel is unavailable without auth.)
# API_BASE/API_KEY seed a shared default provider if you want shared mode.

API_BASE=http://host.docker.internal:8880/v1
API_KEY=none
COMPUTE_MODE=local
BASE_URL=http://localhost:3003
AUTH_SECRET=<generate-with-openssl-rand-hex-32>
# Optional when you need multiple local origins:
# AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://127.0.0.1:3003

# API_BASE / API_KEY are seeded into the admin "default-openai" shared provider
# on first boot, then no longer read. Manage them in Settings → Admin afterwards.
API_BASE=http://host.docker.internal:8880/v1
API_KEY=none
COMPUTE_MODE=local
BASE_URL=http://localhost:3003
AUTH_SECRET=<generate-with-openssl-rand-hex-32>
# Comma-separated emails to auto-promote to admin on signin.
ADMIN_EMAILS=you@example.com

API_BASE=http://host.docker.internal:8880/v1
API_KEY=none
COMPUTE_MODE=local
USE_EMBEDDED_WEED_MINI=false
S3_BUCKET=your-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
# Optional for non-AWS providers:
# S3_ENDPOINT=https://your-s3-compatible-endpoint
# S3_FORCE_PATH_STYLE=true

API_BASE=http://host.docker.internal:8880/v1
API_KEY=none
COMPUTE_MODE=worker
COMPUTE_WORKER_URL=http://localhost:8081
COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
USE_EMBEDDED_WEED_MINI=false
S3_BUCKET=your-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
# Optional for non-AWS providers:
# S3_ENDPOINT=https://your-s3-compatible-endpoint
# S3_FORCE_PATH_STYLE=true

:::note Env vars vs. admin panel On first boot, API_KEY / API_BASE and any RUNTIME_SEED_* flags you've set get auto-seeded into the admin-managed runtime config (DB-backed, keys encrypted at rest). After that, the admin UI is authoritative and editing those env vars no longer changes app behavior. See Admin Panel. :::

:::note User BYOK restriction default If you want each user to enter personal provider credentials, set restrictUserApiKeys=false (from Settings → Admin when auth/admin is enabled, or via legacy first-boot seed RUNTIME_SEED_RESTRICT_USER_API_KEYS=false for no-admin bootstrap flows). :::

:::info For all environment variables, see Environment Variables. :::

See Auth for app/auth behavior. See Admin Panel for the shared-provider and feature-flag management UI. Storage configuration details are in Object / Blob Storage. Refer to Database for database modes. Learn about migration behavior and commands in Migrations.

4. Start the app.

pnpm dev

pnpm build
pnpm start

:::warning API Base Reachability API_BASE must be reachable from the Next.js server process, not just your browser. :::

Visit http://localhost:3003.

Optional workflows

Run manual DB migrations only for troubleshooting or explicit migration workflows:

• Migrations run automatically on startup through the shared entrypoint for both pnpm dev and pnpm start.

pnpm migrate

:::info If POSTGRES_URL is set, migrations target Postgres; otherwise local SQLite is used. To disable automatic startup migrations, set RUN_DRIZZLE_MIGRATIONS=false and/or RUN_FS_MIGRATIONS=false. You can run storage migration manually with pnpm migrate-fs. :::