Local Development

Prerequisites

• Node.js (recommended with nvm)
• pnpm (recommended) or npm

npm install -g pnpm

• A reachable TTS API server
• SeaweedFS weed binary (required unless using external S3 storage)

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.

macOS

brew install seaweedfs

Linux

Install the weed binary from the SeaweedFS releases and ensure it is available on PATH.

Optional, depending on features:

• libreoffice (required for DOCX conversion)

brew install libreoffice

• whisper.cpp (optional, for word-by-word highlighting)

# clone and build whisper.cpp (no model download needed – OpenReader handles that)
git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp
cmake -B build
cmake --build build -j --config Release

# point OpenReader to the compiled whisper-cli binary
echo WHISPER_CPP_BIN="$(pwd)/build/bin/whisper-cli"

tip

Set WHISPER_CPP_BIN in your .env to enable word-by-word highlighting.

Steps

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.

• No auth mode: leave BASE_URL or AUTH_SECRET unset.
• Auth enabled mode: set both BASE_URL (typically http://localhost:3003) and AUTH_SECRET (generate with openssl rand -hex 32).

Optional:

• AUTH_TRUSTED_ORIGINS=http://localhost:3003,http://192.168.0.116:3003
• Stable S3 credentials via S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY
• External S3 storage by setting USE_EMBEDDED_WEED_MINI=false and related S3 vars

info

For all environment variables, see Environment Variables.

See Auth for app/auth behavior. Storage configuration details are in Object / Blob Storage. Refer to Database for database modes. Learn about migration behavior and commands in Migrations.

4. Run DB migrations.

• Migrations run automatically on startup through the shared entrypoint for both pnpm dev and pnpm start.
• You only need manual migration commands for one-off troubleshooting or explicit migration workflows:

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.

5. Start the app.

Dev

pnpm dev

Build + Start

pnpm build
pnpm start

API Base Reachability

API_BASE must be reachable from the Next.js server process, not just your browser.

Visit http://localhost:3003.