Local Development
Run OpenReader from a checkout to work on it. To run it from source without changing code, Docker Compose with a local-build file is usually simpler.
Prerequisites
| Tool | Needed | Why |
|---|---|---|
| Node.js 26 and pnpm 12 | Always | Runs the app. The repository pins the exact pnpm version. |
weed (SeaweedFS) | Unless you use external S3 | Embedded object storage. |
nats-server | Unless you use an external worker | The embedded worker's job queue. |
soffice (LibreOffice) | Optional | DOCX conversion. Without it, DOCX uploads fail. |
FFmpeg and the worker's models need no install: pnpm i brings an FFmpeg build (FFMPEG_BIN overrides it), and models download into docstore/model the first time they are needed.
- macOS
- Linux (amd64)
brew install node pnpm seaweedfs nats-server
brew install --cask libreoffice # optional
Install Node.js 26 (for example with nvm), then:
npm install -g pnpm@12 # Node.js 25 and later no longer bundle Corepack
mkdir -p "$HOME/.local/bin" && cd /tmp
# SeaweedFS 4.48, the version Docker ships
curl -fsSL https://github.com/seaweedfs/seaweedfs/releases/download/4.48/linux_amd64.tar.gz | tar -xz weed
install -m 0755 weed "$HOME/.local/bin/weed"
# NATS
curl -fsSLO https://github.com/nats-io/nats-server/releases/download/v2.12.1/nats-server-v2.12.1-linux-amd64.zip
unzip -j nats-server-v2.12.1-linux-amd64.zip '*/nats-server'
install -m 0755 nats-server "$HOME/.local/bin/nats-server"
sudo apt install -y libreoffice # optional
Make sure $HOME/.local/bin is on your PATH.
pnpm 10 and earlier cannot switch to the pinned version and stop with an error. Upgrade with brew upgrade pnpm, or npm install -g pnpm@12 where npm installed it.
Run it
git clone https://github.com/richardr1126/openreader.git
cd openreader
pnpm i
cp .env.example .env
In .env, set:
BASE_URL=http://localhost:3003
AUTH_SECRET=<output of: openssl rand -base64 32>
That is a complete configuration. The app starts its own storage, queue and compute worker, and generates or derives the worker and playback secrets. Keep AUTH_SECRET stable: it also encrypts saved provider keys.
pnpm dev
Open http://localhost:3003. If anything is missing or misconfigured, startup lists every problem at once and exits.
To run a production build instead, use pnpm build then pnpm start. The build compiles the worker to JavaScript; pnpm dev runs it from its TypeScript sources.
Migrations and scheduled tasks run automatically, as on any self-hosted install.
Optional settings
Add any of these to the same .env.
First administrator. Create an admin account on first boot, then sign in and change the password (details):
BOOTSTRAP_ADMIN_EMAIL=owner@example.com
BOOTSTRAP_ADMIN_PASSWORD=<unique-initial-password-at-least-16-characters>
A TTS server you already run. Adds it as a shared provider on first boot; manage it afterwards in Settings → Admin → Providers (which address to use):
API_BASE=http://127.0.0.1:8880/v1
API_MODEL_NAME=kokoro
# API_KEY=<only if your server requires one>
External S3 instead of the embedded SeaweedFS (details):
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
S3_INTERNAL_ENDPOINT=https://s3.us-east-1.amazonaws.com
# Browsers download through the app. For presigned URLs instead, remove this
# line and set S3_PUBLIC_ENDPOINT to a public HTTPS endpoint.
S3_BROWSER_TRANSPORT=proxy
# Non-AWS providers that need path-style URLs: S3_FORCE_PATH_STYLE=true
An external worker instead of the embedded one. Set COMPUTE_WORKER_URL and the three shared values described in Compute Worker.
After signing in as an admin, Settings → Admin → Maintenance confirms the worker, storage and providers are healthy.
Run the tests
pnpm test
Vitest uses a migrated temporary SQLite database, never docstore/ or POSTGRES_URL.
pnpm test:e2e
Playwright starts and stops its own stack, so port 3003 must be free first. Stop any stack you started yourself.
Generate migrations
After changing the database schema, generate migration files for both SQLite and Postgres:
pnpm generate
This runs the Better Auth CLI to regenerate the auth table schemas, then drizzle-kit generate for both dialects. Running drizzle-kit generate directly skips the Better Auth step.
| Files | Owner |
|---|---|
packages/database/src/schema_sqlite.ts, schema_postgres.ts | App tables. Edit by hand and keep both dialects in sync. |
packages/database/src/schema_auth_sqlite.ts, schema_auth_postgres.ts | Auth tables, generated by Better Auth. Do not edit. |
packages/database/migrations/{sqlite,postgres}/ | Generated SQL and meta/_journal.json for each dialect. |
To apply migrations by hand, run pnpm migrate (Postgres when POSTGRES_URL is set, otherwise SQLite). See Database and Migrations.