danvics/openreader
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openreader/docs-site/docs/deploy/local-development.md
Richard R 4d13b5b821 refactor: improve async state and session reliability 
Implement AbortController in ConfigContext, PDFContext, and preference sync to prevent race conditions during session changes or rapid navigation. Refactor document preview routes into shared utilities and add LRU caching for text previews to optimize memory. Update documentation for Better Auth schema ownership and migration workflows. Fix issues with Postgres system user seeding and better-sqlite3 configuration.
2026-02-15 15:13:25 -07:00

3.4 KiB
Raw Blame History

title
Local Development

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

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)
brew install seaweedfs

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

Optional, depending on features:

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-WebUI.git
cd OpenReader-WebUI
  1. Install dependencies.
pnpm i
  1. 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 -base64 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.

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

  1. 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.