docs: snapshot v3.0.0
This commit is contained in:
github-actions[bot]
parent
ff62cc702e
commit
3645b7a327
26 changed files with 2339 additions and 0 deletions
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
title: Acknowledgements
|
||||
---
|
||||
|
||||
This project is built with support from the following open-source projects and tools:
|
||||
|
||||
- [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M)
|
||||
- [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
|
||||
- [Better Auth](https://www.better-auth.com/)
|
||||
- [SQLite](https://www.sqlite.org/)
|
||||
- [PostgreSQL](https://www.postgresql.org/)
|
||||
- [SeaweedFS](https://github.com/seaweedfs/seaweedfs)
|
||||
- [whisper.cpp](https://github.com/ggerganov/whisper.cpp)
|
||||
- [ffmpeg](https://ffmpeg.org)
|
||||
- [react-pdf](https://github.com/wojtekmaj/react-pdf)
|
||||
- [react-reader](https://github.com/happyr/react-reader)
|
||||
7
docs-site/versioned_docs/version-v3.0.0/about/license.md
Normal file
7
docs-site/versioned_docs/version-v3.0.0/about/license.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: License
|
||||
---
|
||||
|
||||
OpenReader is licensed under the MIT License.
|
||||
|
||||
- Repository license file: [LICENSE](https://github.com/richardr1126/openreader/blob/main/LICENSE)
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: Support and Contributing
|
||||
---
|
||||
|
||||
## Feature requests
|
||||
|
||||
Use [GitHub Discussions](https://github.com/richardr1126/openreader/discussions) for feature requests and ideas.
|
||||
|
||||
## Issues and support
|
||||
|
||||
If you encounter a bug, open an issue in [GitHub Issues](https://github.com/richardr1126/openreader/issues).
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome.
|
||||
|
||||
- Fork the repository
|
||||
- Create your branch
|
||||
- Open a pull request with your changes
|
||||
120
docs-site/versioned_docs/version-v3.0.0/configure/admin-panel.md
Normal file
120
docs-site/versioned_docs/version-v3.0.0/configure/admin-panel.md
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
---
|
||||
title: Admin Panel
|
||||
---
|
||||
|
||||
The admin panel lets a designated set of users manage **shared TTS providers** and **site-wide feature flags** directly from the Settings modal — without touching env vars or redeploying.
|
||||
|
||||
It is gated behind authentication, so you must have auth enabled to use it ([Auth](./auth)).
|
||||
|
||||
## Designating admins
|
||||
|
||||
Set `ADMIN_EMAILS` to a comma-separated list of emails:
|
||||
|
||||
```env
|
||||
AUTH_SECRET=... # required for auth
|
||||
BASE_URL=... # required for auth
|
||||
ADMIN_EMAILS=alice@example.com,bob@example.com
|
||||
```
|
||||
|
||||
On every session resolution the server compares the user's email against this list and writes `user.is_admin = true` (or `false` for emails removed from the list). No restart is required to demote — the next page load picks it up.
|
||||
|
||||
When the logged-in user is an admin, an **Admin** tab appears in **Settings → sidebar** with two sub-tabs:
|
||||
|
||||
- **Shared providers** — server-side TTS provider instances visible to all users.
|
||||
- **Site features** — runtime-editable replacements for what were previously `NEXT_PUBLIC_*` build-time flags.
|
||||
|
||||
## Shared TTS providers
|
||||
|
||||
Each shared provider is one named instance bound to one of the four built-in provider types (`custom-openai`, `openai`, `replicate`, `deepinfra`). The admin form has:
|
||||
|
||||
| Field | Notes |
|
||||
| --- | --- |
|
||||
| **Slug** | URL-safe identifier exposed to users (e.g. `kokoro-prod`). Must not collide with a built-in id. Lowercase alphanumeric + hyphens. |
|
||||
| **Display name** | Shown in the user's provider dropdown, suffixed with "(shared)". |
|
||||
| **Provider type** | One of the four built-ins. Determines voice/model resolution. |
|
||||
| **Base URL** | Optional. Falls through to the provider type's default when blank. |
|
||||
| **API key** | Encrypted at rest with AES-256-GCM (key derived from `AUTH_SECRET` via scrypt). On edit, leave blank to keep the existing key. |
|
||||
| **Default model** | Optional. Used as the initial model when a user selects this provider. |
|
||||
| **Enabled** | Toggle to hide the provider from non-admin users without deleting it. |
|
||||
|
||||
When a non-admin user picks a shared provider in **Settings → TTS Provider**:
|
||||
|
||||
- The API key / base URL fields are hidden — those credentials never leave the server.
|
||||
- The TTS request still goes through the user's browser, but the server replaces the slug with the matching admin row's decrypted key and base URL before calling the upstream provider.
|
||||
- The user's per-request `x-openai-key` / `x-openai-base-url` headers are ignored for shared slugs.
|
||||
|
||||
Whether users can supply their own personal built-in provider keys is controlled by the site feature `restrictUserApiKeys`:
|
||||
|
||||
- `true`: users are restricted to shared providers only.
|
||||
- `false`: users may also use per-user BYOK credentials for built-in providers.
|
||||
|
||||
### Auto-seeded "default-openai"
|
||||
|
||||
On first boot, if `admin_providers` is empty and the legacy `API_KEY` env var is set, OpenReader creates a single shared provider with:
|
||||
|
||||
- slug `default-openai`, displayName `Default (from env)`, providerType `custom-openai`
|
||||
- baseUrl from `API_BASE`, apiKey from `API_KEY` (encrypted)
|
||||
- defaultModel set to `kokoro` (you can edit it in Admin → Shared providers)
|
||||
|
||||
After this seed runs, the legacy `API_KEY` / `API_BASE` env vars are no longer read by the TTS routes — the DB row is authoritative. You can rename, edit, disable, or delete this row like any other from the admin UI, and remove the env vars from your `.env` when convenient.
|
||||
|
||||
:::warning Upgrading from v2.2.0
|
||||
In v2.2.0 and earlier, `API_KEY` / `API_BASE` were read live by the TTS routes on every request. As of v3.0.0 they are **one-shot seeds** consumed only on the first boot where `admin_providers` is empty. After upgrading, boot the app once and confirm a `default-openai` row exists in **Settings → Admin → Shared providers** with the correct base URL. If it is missing or wrong (e.g. the env vars were not set on first boot, or the table was already non-empty from a pre-release), create or edit the shared provider manually — TTS will not fall back to the env vars.
|
||||
:::
|
||||
|
||||
## Site features
|
||||
|
||||
Runtime-editable settings, one row per key:
|
||||
|
||||
| Key | What it controls |
|
||||
| --- | --- |
|
||||
| `defaultTtsProvider` | Default provider id new users start with (built-in id or shared slug). |
|
||||
| `changelogFeedUrl` | Public changelog manifest URL used by the Settings modal changelog panel. |
|
||||
| `enableUserSignups` | Controls whether new accounts can be created. Existing accounts can still sign in when this is `false`. |
|
||||
| `restrictUserApiKeys` | Restrict user-supplied API keys/base URLs; when `true`, only admin shared providers are allowed. |
|
||||
| `enableTtsProvidersTab` | Whether the user-facing TTS Provider tab in Settings is shown. |
|
||||
| `showAllProviderModels` | When `false`, users are restricted to each provider's default model (shared provider `defaultModel` or built-in provider default). |
|
||||
| `enableWordHighlight` | Enable whisper.cpp word-by-word highlighting during TTS playback. |
|
||||
| `enableAudiobookExport` | Show the audiobook export entry points on PDF/EPUB pages. |
|
||||
| `enableDocxConversion` | Accept .docx uploads (converted to PDF server-side). |
|
||||
| `enableDestructiveDeleteActions` | Show "Delete all data" buttons in the Documents tab (auth-disabled mode). |
|
||||
|
||||
Each row shows a source badge:
|
||||
|
||||
- **from env** — the value was migrated from the corresponding `NEXT_PUBLIC_*` env var on first boot. Editing it in the UI flips the source to **admin**.
|
||||
- **admin** — explicit admin override. Use **Reset** on the row to clear it back to the env-default state.
|
||||
- **default** — neither env nor admin set; uses the built-in default.
|
||||
|
||||
:::warning Security note for `restrictUserApiKeys`
|
||||
Turning `restrictUserApiKeys` off allows user-supplied API keys to flow through this server. Use this only for trusted/self-hosted deployments where that tradeoff is acceptable.
|
||||
:::
|
||||
|
||||
## Migrating off env vars
|
||||
|
||||
The future-direction goal is to remove `NEXT_PUBLIC_*` / `API_KEY` / `API_BASE` from your `.env` entirely. To do that safely:
|
||||
|
||||
1. Deploy this version with your existing env values in place.
|
||||
2. Boot the app once. Open Settings → Admin and verify:
|
||||
- Each `NEXT_PUBLIC_*` setting appears as **from env**.
|
||||
- A `default-openai` row exists in **Shared providers** (if you had `API_KEY` set).
|
||||
3. Remove the env vars from your `.env`.
|
||||
4. Redeploy. Behavior is unchanged — the DB is now the source of truth.
|
||||
|
||||
You can keep the env vars indefinitely if you prefer; they're only read on the first boot when the corresponding DB row is absent, so there's no harm in leaving them around.
|
||||
|
||||
## How keys are protected
|
||||
|
||||
- API keys are encrypted in the `admin_providers` table with AES-256-GCM. The encryption key is derived from `AUTH_SECRET` via `scrypt`.
|
||||
- The masked-list view (`GET /api/admin/providers`, used by the admin UI itself) returns `••••` + last-4 only — never plaintext or ciphertext.
|
||||
- The public list endpoint (`GET /api/tts/shared-providers`, called by every user's browser) returns only `{ slug, displayName, providerType, defaultModel }`. Keys and base URLs are never exposed to the client.
|
||||
- Non-admin users cannot enumerate admin providers' credentials or base URLs through any API.
|
||||
|
||||
:::danger Rotating `AUTH_SECRET` invalidates all stored admin provider keys
|
||||
Because the encryption key for `admin_providers` is derived from `AUTH_SECRET`, changing `AUTH_SECRET` makes every stored API key undecryptable. After rotating it, shared providers will fail to authenticate upstream until you re-enter each provider's API key in **Settings → Admin → Shared providers** (edit the row and paste the key again). There is no automated re-encryption path. If you must rotate `AUTH_SECRET`, plan to re-enter admin provider keys immediately afterward.
|
||||
:::
|
||||
|
||||
## Related
|
||||
|
||||
- [Auth](./auth) — required to use the admin panel.
|
||||
- [TTS Providers](./tts-providers) — built-in provider catalog and per-user behavior.
|
||||
- [Environment Variables](../reference/environment-variables) — `ADMIN_EMAILS` and the legacy flags that the admin UI replaces.
|
||||
70
docs-site/versioned_docs/version-v3.0.0/configure/auth.md
Normal file
70
docs-site/versioned_docs/version-v3.0.0/configure/auth.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: Auth
|
||||
---
|
||||
|
||||
This page covers application-level configuration for provider access and authentication.
|
||||
|
||||
## Auth behavior
|
||||
|
||||
- Auth is enabled only when both `BASE_URL` and `AUTH_SECRET` are set.
|
||||
- Remove either value to disable auth.
|
||||
- Keep `AUTH_TRUSTED_ORIGINS` empty to trust only `BASE_URL`.
|
||||
- Anonymous auth sessions are disabled by default.
|
||||
- Set `USE_ANONYMOUS_AUTH_SESSIONS=true` to enable anonymous session flows.
|
||||
|
||||
## Runtime modes
|
||||
|
||||
OpenReader effectively has three common runtime modes:
|
||||
|
||||
- **Auth disabled** (`BASE_URL` or `AUTH_SECRET` unset): no admin panel. Shared providers can still exist via first-boot seeding (`API_KEY`/`API_BASE`), but you cannot manage them in-app.
|
||||
- **Auth enabled, non-admin user**: user account/session features are available, but no admin controls.
|
||||
- **Auth enabled, admin user**: full **Settings → Admin** access (shared providers + site features).
|
||||
|
||||
## Admin role
|
||||
|
||||
When auth is enabled, you can designate one or more users as admins via the `ADMIN_EMAILS` env var:
|
||||
|
||||
```env
|
||||
ADMIN_EMAILS=alice@example.com,bob@example.com
|
||||
```
|
||||
|
||||
Admins see a new **Admin** tab in **Settings** with two sub-tabs:
|
||||
|
||||
- **Shared TTS providers** — server-managed TTS provider instances with encrypted keys, visible to all users.
|
||||
- **Site features** — runtime overrides for what were previously `NEXT_PUBLIC_*` build-time flags (including account signup availability, default TTS provider/model, word highlighting, audiobook export, etc.).
|
||||
|
||||
Admin assignment is reconciled on every session resolution, so removing an email from `ADMIN_EMAILS` demotes the user on next login without a restart. See [Admin Panel](./admin-panel) for the full reference.
|
||||
|
||||
## Route behavior
|
||||
|
||||
- `/` is a public landing/onboarding page and remains indexable.
|
||||
- `/app` is the protected app home (document list and uploader UI).
|
||||
- If auth is enabled and a valid session exists (including anonymous), visiting `/` redirects to `/app`.
|
||||
- Protected app routes continue to require auth; when anonymous sessions are disabled and no session exists, users are redirected to `/signin`.
|
||||
|
||||
## Related docs
|
||||
|
||||
- For auth environment variables: [Environment Variables](../reference/environment-variables#auth-and-identity)
|
||||
- For admin role and shared TTS provider config: [Admin Panel](./admin-panel)
|
||||
- For TTS character limits and quota behavior: [TTS Rate Limiting](./tts-rate-limiting)
|
||||
- For provider-specific guidance: [TTS Providers](./tts-providers)
|
||||
- For storage/S3/SeaweedFS behavior: [Object / Blob Storage](./object-blob-storage)
|
||||
- For database mode: [Database](./database)
|
||||
- For migration behavior and commands: [Migrations](./migrations)
|
||||
|
||||
## Sync notes
|
||||
|
||||
### Auth enabled
|
||||
|
||||
- Settings and reading progress are saved to the server.
|
||||
- Updates are not instant push-based sync; they use normal client polling/refresh behavior.
|
||||
- If two devices change the same item around the same time, the newest update wins.
|
||||
|
||||
### Auth disabled
|
||||
|
||||
- Settings and reading progress stay local in the browser (Dexie/IndexedDB).
|
||||
- This avoids no-auth cross-browser conflicts, but there is no cross-device sync.
|
||||
|
||||
## Claim modal note
|
||||
|
||||
- You may still see old anonymous settings/progress available to claim from older deployments.
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
title: Database
|
||||
---
|
||||
|
||||
This page covers database mode selection for OpenReader.
|
||||
|
||||
## Scope of this page
|
||||
|
||||
- Focus: SQL metadata, state, and relational tables.
|
||||
- Not covered here: object key layout and blob transport details (see [Object / Blob Storage](./object-blob-storage)).
|
||||
|
||||
## Database mode
|
||||
|
||||
- SQLite (default): embedded DB at `docstore/sqlite3.db`; good for local/self-host single-instance setups.
|
||||
- Postgres: enabled when `POSTGRES_URL` is set; recommended for production/distributed deployments.
|
||||
|
||||
## What the database stores
|
||||
|
||||
- Document and audiobook metadata/state used by server routes.
|
||||
- Auth/session tables (`user`, `session`, `account`, `verification`) when auth is enabled — schema is auto-generated by Better Auth.
|
||||
- TTS character usage counters (`user_tts_chars`) for daily rate limiting (when enabled).
|
||||
- User settings preferences (`user_preferences`) when auth is enabled.
|
||||
- User reading progress (`user_document_progress`) when auth is enabled.
|
||||
- Document preview job/asset metadata (`document_previews`) for server-side PDF/EPUB thumbnails.
|
||||
- TTS segment metadata (`tts_segments`) for server-side playback caching:
|
||||
- Segment identity + settings hash
|
||||
- Audio object key and duration
|
||||
- Optional alignment payload for word highlighting
|
||||
- Status/error state
|
||||
- Text fingerprint/hash (plaintext segment text is not stored)
|
||||
|
||||
App-specific tables are manually maintained in Drizzle schema files, while auth tables are generated by the Better Auth CLI. Both are migrated together via Drizzle. See [Migrations](./migrations) for details.
|
||||
|
||||
## What the database does not store
|
||||
|
||||
- Raw document file bytes
|
||||
- Audiobook audio bytes
|
||||
- TTS segment audio bytes
|
||||
- Generated preview image bytes
|
||||
|
||||
Those payloads live in object storage. SQL stores the metadata, references, and status.
|
||||
|
||||
## Related variables
|
||||
|
||||
- `POSTGRES_URL`
|
||||
|
||||
For database variable behavior, see [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Migrations](./migrations)
|
||||
- [Object / Blob Storage](./object-blob-storage)
|
||||
- [Auth](./auth)
|
||||
|
||||
## State sync summary
|
||||
|
||||
- With auth enabled, settings and reading progress are stored in SQL and synced from the app.
|
||||
- With auth disabled, settings and reading progress remain local in the browser.
|
||||
- Sync is currently request-based (not realtime push invalidation).
|
||||
150
docs-site/versioned_docs/version-v3.0.0/configure/migrations.md
Normal file
150
docs-site/versioned_docs/version-v3.0.0/configure/migrations.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
title: Migrations
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This page covers migration behavior for both database schema and storage data in OpenReader.
|
||||
|
||||
## Startup migration behavior
|
||||
|
||||
By default, the shared entrypoint runs migrations automatically before app startup in:
|
||||
|
||||
- Docker container startup
|
||||
- `pnpm dev`
|
||||
- `pnpm start`
|
||||
|
||||
Startup migration phases:
|
||||
|
||||
- DB schema migrations (`pnpm migrate`)
|
||||
- Storage/data migration (`pnpm migrate-fs`) for legacy filesystem content into S3 + DB rows
|
||||
|
||||
:::info
|
||||
In most setups, you do not need to run migration commands manually because startup handles this automatically.
|
||||
:::
|
||||
|
||||
### Schema history
|
||||
|
||||
Migrations are applied in order. All of the following ship in v3.0.0; an instance upgrading from v2.2.0 applies `0001`–`0004` in a single startup pass.
|
||||
|
||||
| Migration | Dialects | What it does |
|
||||
| --- | --- | --- |
|
||||
| `0001_tts_segments` | SQLite + Postgres | Creates the original single-table `tts_segments` used by server-side TTS segment caching. |
|
||||
| `0002_add_segment_key_to_tts_segments` | SQLite + Postgres | Adds the `segment_key` column to `tts_segments` for stable locator-independent segment identity. |
|
||||
| `0003_tts_segments_v2_split` | SQLite + Postgres | Replaces `tts_segments` with a normalized two-table model: `tts_segment_entries` (one row per document segment + locator identity) and `tts_segment_variants` (one row per settings combination, holding the cached audio key, status, and alignment). Drops the original `tts_segments` table — no released build (v2.2.0 or earlier) ever populated it, so there is no production data to migrate. |
|
||||
| `0004_admin_panel` | SQLite + Postgres | Creates `admin_providers` (encrypted shared TTS provider rows) and `admin_settings` (runtime site-feature config), and adds the `is_admin` column to the `user` table. Backs the [Admin Panel](./admin-panel). |
|
||||
|
||||
To skip automatic startup migrations:
|
||||
|
||||
- Set `RUN_DRIZZLE_MIGRATIONS=false`
|
||||
- Set `RUN_FS_MIGRATIONS=false`
|
||||
|
||||
:::warning
|
||||
If you disable startup migrations, ensure your deployment process runs migrations before serving traffic.
|
||||
:::
|
||||
|
||||
## Apply migrations
|
||||
|
||||
In most cases, you do not need manual migration commands because startup runs migrations automatically.
|
||||
|
||||
`pnpm migrate` applies migrations for one database target:
|
||||
|
||||
- Postgres when `POSTGRES_URL` is set
|
||||
- SQLite when `POSTGRES_URL` is unset
|
||||
|
||||
You can always override the target explicitly with `--config`.
|
||||
|
||||
<Tabs groupId="apply-migration-commands">
|
||||
<TabItem value="project-scripts" label="Project Scripts" default>
|
||||
|
||||
```bash
|
||||
# Run pending migrations for one target:
|
||||
# - Postgres if POSTGRES_URL is set
|
||||
# - SQLite if POSTGRES_URL is unset
|
||||
pnpm migrate
|
||||
|
||||
# Run storage migration (filesystem -> S3 + DB)
|
||||
pnpm migrate-fs
|
||||
|
||||
# Dry-run storage migration without uploading/deleting
|
||||
pnpm migrate-fs:dry-run
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
|
||||
|
||||
```bash
|
||||
# Migrate SQLite
|
||||
pnpm exec drizzle-kit migrate --config drizzle.config.sqlite.ts
|
||||
|
||||
# Migrate Postgres
|
||||
pnpm exec drizzle-kit migrate --config drizzle.config.pg.ts
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Generate migrations
|
||||
|
||||
`pnpm generate` is a two-phase script for contributors and schema changes:
|
||||
|
||||
1. **Better Auth schema generation** — runs the Better Auth CLI twice (once for SQLite, once for Postgres) to produce auto-generated Drizzle schema files for auth tables (`user`, `session`, `account`, `verification`).
|
||||
2. **Drizzle migration generation** — runs `drizzle-kit generate` for both `drizzle.config.sqlite.ts` and `drizzle.config.pg.ts`, producing SQL migration files from all schema files (app + auth).
|
||||
|
||||
:::note
|
||||
Most users do not need to run `pnpm generate`. Use it when contributing or when you have changed Drizzle schema files and need new migration files.
|
||||
:::
|
||||
|
||||
### Schema ownership
|
||||
|
||||
Auth tables are owned by Better Auth. Their Drizzle schema definitions are auto-generated and should **not** be hand-edited:
|
||||
|
||||
- `src/db/schema_auth_sqlite.ts`
|
||||
- `src/db/schema_auth_postgres.ts`
|
||||
|
||||
App-specific tables are manually maintained in the standard Drizzle schema files:
|
||||
|
||||
- `src/db/schema_sqlite.ts`
|
||||
- `src/db/schema_postgres.ts`
|
||||
|
||||
Both sets of schema files are included in the Drizzle configs, so `drizzle-kit generate` and `drizzle-kit migrate` handle all tables together.
|
||||
|
||||
When app schema changes (for example `tts_segments`), keep these in sync:
|
||||
|
||||
- `src/db/schema_sqlite.ts`
|
||||
- `src/db/schema_postgres.ts`
|
||||
- `drizzle/sqlite/*.sql` + `drizzle/sqlite/meta/_journal.json`
|
||||
- `drizzle/postgres/*.sql` + `drizzle/postgres/meta/_journal.json`
|
||||
|
||||
<Tabs groupId="generate-migration-commands">
|
||||
<TabItem value="project-script" label="Project Script" default>
|
||||
|
||||
```bash
|
||||
# Full pipeline: Better Auth CLI + Drizzle generate (both dialects)
|
||||
pnpm generate
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
|
||||
|
||||
```bash
|
||||
# Generate SQLite migrations only (skips Better Auth CLI)
|
||||
pnpm exec drizzle-kit generate --config drizzle.config.sqlite.ts
|
||||
|
||||
# Generate Postgres migrations only (skips Better Auth CLI)
|
||||
pnpm exec drizzle-kit generate --config drizzle.config.pg.ts
|
||||
```
|
||||
|
||||
:::warning
|
||||
Running `drizzle-kit generate` directly skips the Better Auth CLI step. If auth schema has changed upstream (e.g. after a Better Auth version bump), run `pnpm generate` instead to regenerate the auth schema files first.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Database](./database)
|
||||
- [Object / Blob Storage](./object-blob-storage)
|
||||
- [Migration Environment Variables](../reference/environment-variables#migration-controls)
|
||||
|
|
@ -0,0 +1,167 @@
|
|||
---
|
||||
title: Object / Blob Storage
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This page documents storage backends, blob upload routing, and core Docker mount behavior.
|
||||
|
||||
## Scope of this page
|
||||
|
||||
- Focus: object/blob backends, keyspaces, upload/read paths, and storage debugging.
|
||||
- Not covered here: relational metadata tables and SQL state modeling (see [Database](./database)).
|
||||
|
||||
## Storage backends
|
||||
|
||||
- Embedded (default): embedded SeaweedFS (`weed mini`) blob storage.
|
||||
- External: external S3-compatible object storage.
|
||||
|
||||
Metadata database mode (SQLite vs Postgres) is configured separately in [Database](./database).
|
||||
|
||||
:::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.
|
||||
:::
|
||||
|
||||
Storage variables are documented in [Environment Variables](../reference/environment-variables#database-and-object-blob-storage).
|
||||
|
||||
## Ports
|
||||
|
||||
- `3003`: OpenReader app and API routes
|
||||
- `8333`: Embedded SeaweedFS S3 endpoint for direct browser blob access
|
||||
|
||||
:::info
|
||||
`8333` is only needed for direct browser presigned access to embedded SeaweedFS.
|
||||
:::
|
||||
|
||||
## Upload behavior
|
||||
|
||||
- Primary path: browser uploads to presigned URL from `/api/documents/blob/upload/presign`.
|
||||
- Fallback path: `/api/documents/blob/upload/fallback` when direct upload fails/unreachable.
|
||||
- Read/download path: blob/content serving route `/api/documents/blob` (not the upload fallback route).
|
||||
- Preview path: `/api/documents/blob/preview` (returns `202` while a preview is generating; serves/redirects when ready).
|
||||
|
||||
## Document previews
|
||||
|
||||
- PDF/EPUB previews are generated server-side and stored in object storage under `document_previews_v1`.
|
||||
- Preview generation is triggered on upload registration and also backfills on first preview request for older docs.
|
||||
- Preview artifacts are temporary-cache friendly and can be regenerated from the source document blob.
|
||||
|
||||
## FS / Volume Mounts
|
||||
|
||||
### App data mount
|
||||
|
||||
- Target: `/app/docstore`
|
||||
- Recommended: yes, for persistence
|
||||
- Purpose: persists SeaweedFS blob data, SQLite metadata DB, migrations, and local runtime temp state
|
||||
- Mount string: `-v openreader_docstore:/app/docstore`
|
||||
|
||||
### Library source mount (optional)
|
||||
|
||||
- Target: `/app/docstore/library`
|
||||
- Recommended: optional, use read-only (`:ro`)
|
||||
- Purpose: exposes host files as a source for server library import
|
||||
- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
|
||||
- Details: [Server Library Import](./server-library-import)
|
||||
|
||||
## Private blob endpoint mode
|
||||
|
||||
If `8333` is not published externally:
|
||||
|
||||
- Document uploads still work through upload fallback proxy
|
||||
- Reads/snippets continue through app API routes
|
||||
- Direct presigned browser upload/download to embedded endpoint is unavailable
|
||||
|
||||
:::warning
|
||||
Without `8333`, expect higher app-server traffic because uploads/downloads go through API routes instead of direct object endpoint access.
|
||||
:::
|
||||
|
||||
## Audiobook Storage Debug Commands
|
||||
|
||||
Audiobook assets are stored in object storage under the `audiobooks_v1` keyspace. Use these commands to inspect and download objects for debugging.
|
||||
|
||||
<Tabs groupId="audiobook-storage-access-cli">
|
||||
<TabItem value="aws-s3" label="AWS S3" default>
|
||||
|
||||
```bash
|
||||
# List all audiobook objects
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive
|
||||
|
||||
# Filter to one book id (replace <book-id>)
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive | grep "<book-id>-audiobook/"
|
||||
|
||||
# Download one object by full key
|
||||
aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
|
||||
|
||||
```bash
|
||||
# List all audiobook objects
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
|
||||
|
||||
# Filter to one book id (replace <book-id>)
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "<book-id>-audiobook/"
|
||||
|
||||
# Download one object by full key
|
||||
aws s3 cp "s3://$S3_BUCKET/$S3_PREFIX/audiobooks_v1/<path>/<file>.m4b" "./audiobook.m4b" --endpoint-url "$S3_ENDPOINT"
|
||||
```
|
||||
|
||||
Embedded default example: `S3_ENDPOINT=http://127.0.0.1:8333` (or your mapped host/port).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## TTS Segment Storage
|
||||
|
||||
Server-side TTS segment audio is stored in object storage under the `tts_segments_v1` keyspace.
|
||||
|
||||
Typical key layout:
|
||||
|
||||
- `${S3_PREFIX}/tts_segments_v1/users/<url-encoded-user-id>/docs/<document-id>/<document-version>/<settings-hash>/<segment-id>.mp3`
|
||||
- `${S3_PREFIX}/tts_segments_v1/ns/<test-namespace>/users/<url-encoded-user-id>/docs/...` (test namespace mode)
|
||||
|
||||
Notes:
|
||||
|
||||
- For the corresponding SQL metadata model (`tts_segments`), see [Database](./database).
|
||||
|
||||
## Account Deletion Cleanup
|
||||
|
||||
Account deletion performs best-effort object cleanup:
|
||||
|
||||
- Document blobs + preview artifacts
|
||||
- Audiobook blobs
|
||||
- TTS segment blobs under `tts_segments_v1`
|
||||
|
||||
If object deletion fails, account deletion still proceeds and orphaned objects may require manual cleanup.
|
||||
|
||||
## TTS Segment Storage Debug Commands
|
||||
|
||||
Use these commands to inspect segment objects.
|
||||
|
||||
<Tabs groupId="tts-segment-storage-access-cli">
|
||||
<TabItem value="aws-s3" label="AWS S3" default>
|
||||
|
||||
```bash
|
||||
# List all TTS segment objects
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive
|
||||
|
||||
# Filter to one document id (replace <document-id>)
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive | grep "/docs/<document-id>/"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="s3-compatible" label="Embedded / MinIO / R2 / etc">
|
||||
|
||||
```bash
|
||||
# List all TTS segment objects
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT"
|
||||
|
||||
# Filter to one document id (replace <document-id>)
|
||||
aws s3 ls "s3://$S3_BUCKET/$S3_PREFIX/tts_segments_v1/" --recursive --endpoint-url "$S3_ENDPOINT" | grep "/docs/<document-id>/"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: Server Library Import
|
||||
---
|
||||
|
||||
This page documents how server library import works and how to configure it.
|
||||
|
||||
## What it does
|
||||
|
||||
Server library import lets you browse files from one or more server directories and import selected files into OpenReader.
|
||||
|
||||
- Import is user-driven via a selection modal
|
||||
- Only selected files are imported
|
||||
- Imported files become normal OpenReader documents
|
||||
|
||||
## FS / Volume Mounts
|
||||
|
||||
### App data mount
|
||||
|
||||
- Target: `/app/docstore`
|
||||
- Recommended: yes, for persistence
|
||||
- Purpose: stores app runtime data, metadata DB, and embedded storage state
|
||||
- Mount string: `-v openreader_docstore:/app/docstore`
|
||||
|
||||
### Library source mount
|
||||
|
||||
- Target: `/app/docstore/library`
|
||||
- Recommended: yes for this feature, use read-only (`:ro`)
|
||||
- Purpose: exposes host files as import candidates in Server Library Import
|
||||
- Mount string: `-v /path/to/your/library:/app/docstore/library:ro`
|
||||
|
||||
## Import flow
|
||||
|
||||
1. Open **Settings -> Documents -> Server Library Import**.
|
||||
2. Select files in the modal.
|
||||
3. Click **Import**.
|
||||
|
||||
Selected files are fetched from the server library endpoint and imported into OpenReader storage.
|
||||
|
||||
:::warning Shared Library Roots
|
||||
Library roots are configured at the server level (not per-user). Any user who can access Server Library Import can browse/import from the same configured roots.
|
||||
|
||||
Imported documents are still saved to the importing user's document scope.
|
||||
:::
|
||||
|
||||
## Supported file types
|
||||
|
||||
- `.pdf`
|
||||
- `.epub`
|
||||
- `.html`, `.htm`
|
||||
- `.txt`
|
||||
- `.md`, `.mdown`, `.markdown`
|
||||
|
||||
## Optional: Configure Library Roots
|
||||
|
||||
You only need this when the default mounted path is not what you want.
|
||||
|
||||
By default, OpenReader uses `docstore/library` as the import root. You can override that with environment variables:
|
||||
|
||||
- `IMPORT_LIBRARY_DIRS` (takes precedence): multiple roots separated by comma, colon, or semicolon
|
||||
- `IMPORT_LIBRARY_DIR`: single root
|
||||
|
||||
See [Environment Variables](../reference/environment-variables#library-import) for variable details.
|
||||
|
||||
## Notes
|
||||
|
||||
- Library listing is capped per request (up to 10,000 files).
|
||||
- When auth is enabled, library import endpoints require a valid session.
|
||||
- The mounted library is a source; removing it does not delete already imported documents.
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
title: DeepInfra
|
||||
---
|
||||
|
||||
Use DeepInfra's hosted TTS models as your provider.
|
||||
|
||||
## Setup
|
||||
|
||||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||||
|
||||
1. Add a shared provider with type `deepinfra`.
|
||||
2. Keep base URL as `https://api.deepinfra.com/v1/openai`.
|
||||
3. Enter your API key.
|
||||
4. Set your preferred default model/voice.
|
||||
|
||||
**Legacy bootstrap seed (optional, first boot only):**
|
||||
|
||||
```env
|
||||
API_BASE=https://api.deepinfra.com/v1/openai
|
||||
API_KEY=your-deepinfra-key
|
||||
```
|
||||
|
||||
**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
|
||||
|
||||
1. Set provider to `Deepinfra`.
|
||||
2. The base URL is pre-filled, no changes needed.
|
||||
3. Enter your `API_KEY`.
|
||||
4. Choose a model and voice.
|
||||
|
||||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||||
|
||||
## Notes
|
||||
|
||||
- Available models include `hexgrad/Kokoro-82M` and `canopylabs/orpheus-3b-0.1-ft`.
|
||||
- Without an API key, only the free-tier model (`hexgrad/Kokoro-82M`) is shown in the dropdown.
|
||||
- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
|
||||
|
||||
## References
|
||||
|
||||
- [DeepInfra TTS models](https://deepinfra.com/models/text-to-speech)
|
||||
- [TTS Providers](../tts-providers)
|
||||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
title: KittenTTS-FastAPI
|
||||
---
|
||||
|
||||
Run [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider. Lightweight and CPU-friendly.
|
||||
|
||||
## Run KittenTTS
|
||||
|
||||
```bash
|
||||
docker run -it --rm \
|
||||
--name kittentts-fastapi \
|
||||
-e KITTEN_MODEL_REPO_ID="KittenML/kitten-tts-nano-0.8-fp32" \
|
||||
-p 8005:8005 \
|
||||
ghcr.io/richardr1126/kittentts-fastapi-cpu
|
||||
```
|
||||
|
||||
## Connect to OpenReader
|
||||
|
||||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||||
|
||||
1. Add a shared provider with type `custom-openai`.
|
||||
2. Set base URL to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
|
||||
3. Leave API key blank unless required by your deployment.
|
||||
4. Set default model to `kitten-tts` (or your backend model id).
|
||||
|
||||
**Legacy bootstrap seed (optional, first boot only):**
|
||||
|
||||
```env
|
||||
API_BASE=http://kittentts-fastapi:8005/v1
|
||||
```
|
||||
|
||||
> Use `kittentts-fastapi` if that's the container name, or `host.docker.internal` if not.
|
||||
|
||||
**Or in-app via Settings → TTS Provider:**
|
||||
|
||||
1. Set provider to `Custom OpenAI-Like`.
|
||||
2. Set `API_BASE` to your KittenTTS endpoint (e.g. `http://kittentts-fastapi:8005/v1`).
|
||||
3. Leave `API_KEY` blank unless your deployment requires one.
|
||||
4. Choose model `kitten-tts` (or the model your deployment exposes).
|
||||
|
||||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||||
|
||||
## References
|
||||
|
||||
- [richardr1126/KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI)
|
||||
- [TTS Providers](../tts-providers)
|
||||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
title: Kokoro-FastAPI
|
||||
---
|
||||
|
||||
Run [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
|
||||
|
||||
:::warning
|
||||
For Kokoro issues and support, use the upstream repository: [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI).
|
||||
:::
|
||||
|
||||
## Run Kokoro
|
||||
|
||||
**CPU:**
|
||||
|
||||
```bash
|
||||
docker run --name kokoro-tts \
|
||||
--restart unless-stopped \
|
||||
-d \
|
||||
-p 8880:8880 \
|
||||
-e ONNX_NUM_THREADS=8 \
|
||||
-e ONNX_INTER_OP_THREADS=4 \
|
||||
-e ONNX_EXECUTION_MODE=parallel \
|
||||
-e ONNX_OPTIMIZATION_LEVEL=all \
|
||||
-e ONNX_MEMORY_PATTERN=true \
|
||||
-e ONNX_ARENA_EXTEND_STRATEGY=kNextPowerOfTwo \
|
||||
-e API_LOG_LEVEL=DEBUG \
|
||||
ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
|
||||
```
|
||||
|
||||
**GPU (NVIDIA):**
|
||||
|
||||
```bash
|
||||
docker run --name kokoro-tts \
|
||||
--restart unless-stopped \
|
||||
-d \
|
||||
--gpus all \
|
||||
--user 1001:1001 \
|
||||
-p 8880:8880 \
|
||||
-e USE_GPU=true \
|
||||
-e PYTHONUNBUFFERED=1 \
|
||||
-e API_LOG_LEVEL=DEBUG \
|
||||
ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.4
|
||||
```
|
||||
|
||||
## Connect to OpenReader
|
||||
|
||||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||||
|
||||
1. Add a shared provider with type `custom-openai`.
|
||||
2. Set base URL to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
|
||||
3. Leave API key blank unless required by your deployment.
|
||||
4. Set default model to `Kokoro`.
|
||||
|
||||
**Legacy bootstrap seed (optional, first boot only):**
|
||||
|
||||
```env
|
||||
API_BASE=http://kokoro-tts:8880/v1
|
||||
```
|
||||
|
||||
> Use `kokoro-tts` if that's the container name, or `host.docker.internal` if not.
|
||||
|
||||
**Or in-app via Settings → TTS Provider:**
|
||||
|
||||
1. Set provider to `Custom OpenAI-Like`.
|
||||
2. Set `API_BASE` to your Kokoro endpoint (e.g. `http://kokoro-tts:8880/v1`).
|
||||
3. Leave `API_KEY` blank unless your deployment requires one.
|
||||
4. Choose model `Kokoro`.
|
||||
|
||||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||||
|
||||
## References
|
||||
|
||||
- [remsky/Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)
|
||||
- [TTS Providers](../tts-providers)
|
||||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
title: OpenAI
|
||||
---
|
||||
|
||||
Use the OpenAI TTS API as your provider.
|
||||
|
||||
## Setup
|
||||
|
||||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||||
|
||||
1. Add a shared provider with type `openai`.
|
||||
2. Keep base URL as `https://api.openai.com/v1`.
|
||||
3. Enter your API key.
|
||||
4. Set your preferred default model/voice.
|
||||
|
||||
**Legacy bootstrap seed (optional, first boot only):**
|
||||
|
||||
```env
|
||||
API_BASE=https://api.openai.com/v1
|
||||
API_KEY=sk-...
|
||||
```
|
||||
|
||||
**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
|
||||
|
||||
1. Set provider to `OpenAI`.
|
||||
2. The base URL is pre-filled, no changes needed.
|
||||
3. Enter your `API_KEY`.
|
||||
4. Choose a model and voice.
|
||||
|
||||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||||
|
||||
## Notes
|
||||
|
||||
- Models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
|
||||
- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
|
||||
|
||||
## References
|
||||
|
||||
- [OpenAI TTS pricing](https://platform.openai.com/docs/pricing#transcription-and-speech)
|
||||
- [TTS Providers](../tts-providers)
|
||||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
title: Orpheus-FastAPI
|
||||
---
|
||||
|
||||
Run [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI) locally and connect it to OpenReader using the `Custom OpenAI-Like` provider.
|
||||
|
||||
## Run Orpheus
|
||||
|
||||
Refer to the upstream repository for Docker instructions: [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
|
||||
|
||||
## Connect to OpenReader
|
||||
|
||||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||||
|
||||
1. Add a shared provider with type `custom-openai`.
|
||||
2. Set base URL to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
|
||||
3. Leave API key blank unless required by your deployment.
|
||||
4. Set default model to `Orpheus` (or your backend model id).
|
||||
|
||||
**Legacy bootstrap seed (optional, first boot only):**
|
||||
|
||||
```env
|
||||
API_BASE=http://orpheus:8000/v1
|
||||
```
|
||||
|
||||
> Use the container name if that's how it's named, or `host.docker.internal` if not.
|
||||
|
||||
**Or in-app via Settings → TTS Provider:**
|
||||
|
||||
1. Set provider to `Custom OpenAI-Like`.
|
||||
2. Set `API_BASE` to your Orpheus endpoint (e.g. `http://orpheus:8000/v1`).
|
||||
3. Leave `API_KEY` blank unless your deployment requires one.
|
||||
4. Choose model `Orpheus` (or the model your deployment exposes).
|
||||
|
||||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||||
|
||||
## References
|
||||
|
||||
- [Lex-au/Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI)
|
||||
- [TTS Providers](../tts-providers)
|
||||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: Other
|
||||
---
|
||||
|
||||
Use any OpenAI-compatible TTS service with OpenReader, including self-hosted servers not covered by a dedicated guide.
|
||||
|
||||
## Requirements
|
||||
|
||||
Your service must expose these endpoints:
|
||||
|
||||
- `GET /v1/audio/voices`
|
||||
- `POST /v1/audio/speech`
|
||||
|
||||
Known compatible implementations: [Kokoro-FastAPI](./kokoro-fastapi), [KittenTTS-FastAPI](./kitten-tts-fastapi), [Orpheus-FastAPI](./orpheus-fastapi).
|
||||
|
||||
## Setup
|
||||
|
||||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||||
|
||||
1. Add a shared provider with type `custom-openai`.
|
||||
2. Set `API_BASE` to your service base URL (typically ending in `/v1`).
|
||||
3. Set API key if your service requires authentication.
|
||||
4. Set a default model/voice supported by your backend.
|
||||
|
||||
**Legacy bootstrap seed (optional, first boot only):**
|
||||
|
||||
```env
|
||||
API_BASE=http://your-tts-server/v1
|
||||
API_KEY=optional-key-if-required
|
||||
```
|
||||
|
||||
**Or in-app via Settings → TTS Provider:**
|
||||
|
||||
1. Set provider to `Custom OpenAI-Like`.
|
||||
2. Set `API_BASE` to your service's base URL (typically ending in `/v1`).
|
||||
3. Set `API_KEY` if your service requires authentication.
|
||||
4. Choose a model and voice supported by your backend.
|
||||
|
||||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||||
|
||||
:::warning TTS requests are server-side
|
||||
`API_BASE` must be reachable from the **Next.js server**, not just the browser. In Docker, use container names or `host.docker.internal`.
|
||||
:::
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If voices don't load, check that `/v1/audio/voices` is reachable from the server and returns a valid response shape.
|
||||
|
||||
## References
|
||||
|
||||
- [TTS Providers](../tts-providers)
|
||||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
title: Replicate
|
||||
---
|
||||
|
||||
Use Replicate's hosted TTS models as your provider.
|
||||
|
||||
## Setup
|
||||
|
||||
**Recommended (auth + admin): Settings → Admin → Shared providers**
|
||||
|
||||
1. Add a shared provider with type `replicate`.
|
||||
2. Enter your API key.
|
||||
3. Set default model to:
|
||||
`alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5` (or your preferred model).
|
||||
|
||||
**Legacy bootstrap seed (optional, first boot only):**
|
||||
|
||||
```env
|
||||
API_KEY=r8_...
|
||||
```
|
||||
|
||||
Then update the shared provider's **Default model** in **Settings → Admin → Shared providers**.
|
||||
|
||||
**Per-user Settings → TTS Provider (only when `restrictUserApiKeys=false`):**
|
||||
|
||||
1. Set provider to `Replicate`.
|
||||
2. Enter your `API_KEY`.
|
||||
3. Choose a model and voice.
|
||||
|
||||
See [TTS Providers](../tts-providers) for admin-shared vs per-user behavior.
|
||||
|
||||
## Notes
|
||||
|
||||
- Built-in Replicate models:
|
||||
- `alphanumericuser/kokoro-82m:89b6fa84e4fa2dd6bd3a96be3e1f12827a3516c9fda8fddbac7a0be131c9a6f5`
|
||||
- `google/gemini-3.1-flash-tts`
|
||||
- `minimax/speech-2.8-turbo`
|
||||
- `qwen/qwen3-tts`
|
||||
- `inworld/tts-1.5-mini`
|
||||
- You can also choose `Other` and enter any Replicate model ID (for example `owner/model-name` or `owner/model-name:version`).
|
||||
- Native model speed is not available on all Replicate models; OpenReader hides/disables native speed controls where unsupported.
|
||||
- TTS requests are sent from the server, not the browser. The API key is never exposed to clients.
|
||||
|
||||
## References
|
||||
|
||||
- [Replicate](https://replicate.com/explore)
|
||||
- [TTS Providers](../tts-providers)
|
||||
- [TTS Environment Variables](../../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
title: TTS Providers
|
||||
---
|
||||
|
||||
OpenReader routes all TTS requests through the Next.js server to an OpenAI-compatible API. There are three places provider configuration can live:
|
||||
|
||||
**Admin-managed shared providers** (Settings > Admin > Shared providers): DB-backed instances configured by an admin and visible to all users. Keys are encrypted at rest and never exposed to the client. Available only when [auth is enabled](./auth) and your account is in `ADMIN_EMAILS`. See [Admin Panel](./admin-panel).
|
||||
|
||||
**Per-user Settings modal** (Settings > TTS Provider): provider + API key stored in the user's browser and sent with every TTS request. This path is available only when the admin/runtime setting `restrictUserApiKeys=false`.
|
||||
|
||||
**Environment variables**: `API_KEY` and `API_BASE` exist as a one-shot first-boot seed that auto-creates a `default-openai` admin shared provider. After the first boot they are no longer read by the running app.
|
||||
|
||||
:::tip
|
||||
If you're running a private/self-hosted instance and want per-user BYOK behavior, turn off **Settings → Admin → Site features → Restrict user API keys**. Legacy first-boot seed via `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` is still supported for no-admin bootstrap flows.
|
||||
:::
|
||||
|
||||
## Providers
|
||||
|
||||
- **OpenAI**: Cloud. Base URL pre-filled (`https://api.openai.com/v1`). API key required.
|
||||
- **Replicate**: Cloud. Base URL managed internally by OpenReader. API key required.
|
||||
- **DeepInfra**: Cloud. Base URL pre-filled (`https://api.deepinfra.com/v1/openai`). API key required.
|
||||
- **Custom OpenAI-Like**: Self-hosted or any custom endpoint. `API_BASE` must be set manually (typically ending in `/v1`). API key optional.
|
||||
|
||||
For `OpenAI`, `DeepInfra`, and `Replicate` you only need to supply an API key. For `Custom OpenAI-Like` you must also set `API_BASE`.
|
||||
|
||||
## Built-in model catalogs
|
||||
|
||||
- **Replicate** models: `alphanumericuser/kokoro-82m`, `google/gemini-3.1-flash-tts`, `minimax/speech-2.8-turbo`, `qwen/qwen3-tts`, `inworld/tts-1.5-mini` (or choose `Other` and enter any Replicate model ID, such as `owner/model` or `owner/model:version`)
|
||||
- **OpenAI** models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
|
||||
- **DeepInfra** models: includes `hexgrad/Kokoro-82M` and additional hosted models (depending on API key / feature flags)
|
||||
|
||||
## Custom provider requirements
|
||||
|
||||
Self-hosted or custom providers must expose OpenAI-compatible audio endpoints:
|
||||
|
||||
- `GET /v1/audio/voices`
|
||||
- `POST /v1/audio/speech`
|
||||
|
||||
:::warning TTS requests are server-side
|
||||
TTS requests originate from the **Next.js server**, not the browser. `API_BASE` must be reachable from the server runtime. In Docker, use container names or `host.docker.internal` rather than `localhost`.
|
||||
:::
|
||||
|
||||
## Provider guides
|
||||
|
||||
- [Kokoro-FastAPI](./tts-provider-guides/kokoro-fastapi)
|
||||
- [KittenTTS-FastAPI](./tts-provider-guides/kitten-tts-fastapi)
|
||||
- [Orpheus-FastAPI](./tts-provider-guides/orpheus-fastapi)
|
||||
- [Replicate](./tts-provider-guides/replicate)
|
||||
- [DeepInfra](./tts-provider-guides/deepinfra)
|
||||
- [OpenAI](./tts-provider-guides/openai)
|
||||
- [Other](./tts-provider-guides/other)
|
||||
|
||||
## Related
|
||||
|
||||
- [Admin Panel](./admin-panel) — DB-backed shared providers with encrypted keys
|
||||
- [TTS Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
- [TTS Rate Limiting](./tts-rate-limiting)
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
title: TTS Rate Limiting
|
||||
---
|
||||
|
||||
This page explains OpenReader's TTS character rate limiting controls.
|
||||
|
||||
## Overview
|
||||
|
||||
- TTS rate limiting is disabled by default.
|
||||
- To enable it, set `TTS_ENABLE_RATE_LIMIT=true`.
|
||||
- Limits are enforced per day in UTC.
|
||||
- Enforcement applies only when auth is enabled.
|
||||
|
||||
## How enforcement works
|
||||
|
||||
When enabled, OpenReader enforces:
|
||||
|
||||
- Per-user daily character limits.
|
||||
- IP backstop daily character limits.
|
||||
- Anonymous device backstop tracking (cookie-based) to reduce limit resets.
|
||||
|
||||
If a request exceeds the active limit, the TTS API returns `429` with reset metadata for the next UTC day.
|
||||
|
||||
## Required auth behavior
|
||||
|
||||
- Auth must be enabled (`BASE_URL` + `AUTH_SECRET`) for TTS char limits to apply.
|
||||
- If auth is disabled, TTS character limits are effectively unlimited.
|
||||
- `DISABLE_AUTH_RATE_LIMIT` only affects Better Auth's own request throttling.
|
||||
- `DISABLE_AUTH_RATE_LIMIT` does not disable TTS character limits.
|
||||
|
||||
## Environment variables
|
||||
|
||||
Enable/disable:
|
||||
|
||||
- `TTS_ENABLE_RATE_LIMIT` (default: `false`)
|
||||
|
||||
Per-user daily limits:
|
||||
|
||||
- `TTS_DAILY_LIMIT_ANONYMOUS` (default: `50000`)
|
||||
- `TTS_DAILY_LIMIT_AUTHENTICATED` (default: `500000`)
|
||||
|
||||
IP backstop daily limits:
|
||||
|
||||
- `TTS_IP_DAILY_LIMIT_ANONYMOUS` (default: `100000`)
|
||||
- `TTS_IP_DAILY_LIMIT_AUTHENTICATED` (default: `1000000`)
|
||||
|
||||
## Related docs
|
||||
|
||||
- TTS/rate-limit environment variables: [Environment Variables](../reference/environment-variables#tts-provider-and-request-behavior)
|
||||
- Auth configuration: [Auth](./auth)
|
||||
- Provider setup: [TTS Providers](./tts-providers)
|
||||
|
|
@ -0,0 +1,303 @@
|
|||
---
|
||||
title: Local Development
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<details>
|
||||
<summary><strong>Node.js + pnpm (required)</strong></summary>
|
||||
|
||||
<Tabs groupId="local-dev-node-pnpm-os">
|
||||
<TabItem value="macos" label="macOS" default>
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>SeaweedFS <code>weed</code> binary (required unless using external S3)</strong></summary>
|
||||
|
||||
<Tabs groupId="local-dev-seaweed-os">
|
||||
<TabItem value="macos" label="macOS" default>
|
||||
|
||||
```bash
|
||||
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.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>LibreOffice (optional, for DOCX conversion)</strong></summary>
|
||||
|
||||
<Tabs groupId="local-dev-libreoffice-os">
|
||||
<TabItem value="macos" label="macOS" default>
|
||||
|
||||
```bash
|
||||
brew install libreoffice
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu example
|
||||
sudo apt update
|
||||
sudo apt install -y libreoffice
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>whisper.cpp (optional, for word-by-word highlighting)</strong></summary>
|
||||
|
||||
Install build dependencies:
|
||||
|
||||
<Tabs groupId="local-dev-whisper-deps-os">
|
||||
<TabItem value="macos" label="macOS" default>
|
||||
|
||||
```bash
|
||||
brew install cmake
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu example
|
||||
sudo apt update
|
||||
sudo apt install -y git build-essential cmake
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Build whisper.cpp:
|
||||
|
||||
```bash
|
||||
# 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"
|
||||
```
|
||||
|
||||
If you are not on Debian/Ubuntu, install equivalent packages with your distro package manager:
|
||||
|
||||
- Fedora/RHEL: use `dnf` (`gcc gcc-c++ make cmake curl git tar xz`)
|
||||
- Arch: use `pacman` (`base-devel cmake curl git tar xz`)
|
||||
|
||||
:::tip
|
||||
Set `WHISPER_CPP_BIN` in your `.env` to enable word-by-word highlighting.
|
||||
:::
|
||||
|
||||
</details>
|
||||
|
||||
## Steps
|
||||
|
||||
### Required flow
|
||||
|
||||
1. Clone the repository.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/richardr1126/openreader.git
|
||||
cd openreader
|
||||
```
|
||||
|
||||
2. Install dependencies.
|
||||
|
||||
```bash
|
||||
pnpm i
|
||||
```
|
||||
|
||||
3. Configure the environment.
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Then edit `.env`.
|
||||
|
||||
Use one of these `.env` mode templates:
|
||||
|
||||
<Tabs groupId="local-env-modes">
|
||||
<TabItem value="no-auth" label="No Auth (simple)" default>
|
||||
|
||||
```env
|
||||
API_BASE=http://host.docker.internal:8880/v1
|
||||
API_KEY=none
|
||||
# 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.
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="auth-enabled" label="Auth Enabled">
|
||||
|
||||
```env
|
||||
API_BASE=http://host.docker.internal:8880/v1
|
||||
API_KEY=none
|
||||
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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="auth-with-admin" label="Auth + Admin Panel">
|
||||
|
||||
```env
|
||||
# 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
|
||||
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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="external-s3" label="External S3">
|
||||
|
||||
```env
|
||||
API_BASE=http://host.docker.internal:8880/v1
|
||||
API_KEY=none
|
||||
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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::note Env vars vs. admin panel
|
||||
On first boot, `API_KEY` / `API_BASE` and any `NEXT_PUBLIC_*` 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](../configure/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 `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` for no-admin bootstrap flows).
|
||||
:::
|
||||
|
||||
:::info
|
||||
For all environment variables, see [Environment Variables](../reference/environment-variables).
|
||||
:::
|
||||
|
||||
See [Auth](../configure/auth) for app/auth behavior.
|
||||
See [Admin Panel](../configure/admin-panel) for the shared-provider and feature-flag management UI.
|
||||
Storage configuration details are in [Object / Blob Storage](../configure/object-blob-storage).
|
||||
Refer to [Database](../configure/database) for database modes.
|
||||
Learn about migration behavior and commands in [Migrations](../configure/migrations).
|
||||
|
||||
4. Start the app.
|
||||
|
||||
<Tabs groupId="local-run-mode">
|
||||
<TabItem value="dev" label="Dev (recommended)" default>
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="prod" label="Build + Start">
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
pnpm start
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::warning API Base Reachability
|
||||
`API_BASE` must be reachable from the Next.js server process, not just your browser.
|
||||
:::
|
||||
|
||||
Visit [http://localhost:3003](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`.
|
||||
|
||||
```bash
|
||||
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`.
|
||||
:::
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
---
|
||||
title: Vercel Deployment
|
||||
---
|
||||
|
||||
This guide covers deploying OpenReader to Vercel with external Postgres and S3-compatible object storage.
|
||||
|
||||
## What works on Vercel
|
||||
|
||||
- Documents (PDF/EPUB/TXT/MD) work with `POSTGRES_URL` + external S3 storage.
|
||||
- Audiobook routes work on Node.js serverless functions using `ffmpeg-static`.
|
||||
|
||||
:::warning DOCX Conversion Limitation
|
||||
`docx` conversion requires `soffice` (LibreOffice), which is not available in a standard Vercel runtime.
|
||||
:::
|
||||
|
||||
## 1. Environment Variables
|
||||
|
||||
Recommended production setup (auth enabled, admin panel enabled):
|
||||
|
||||
```bash
|
||||
# Infrastructure
|
||||
POSTGRES_URL=postgres://...
|
||||
USE_EMBEDDED_WEED_MINI=false
|
||||
S3_ACCESS_KEY_ID=...
|
||||
S3_SECRET_ACCESS_KEY=...
|
||||
S3_BUCKET=...
|
||||
S3_REGION=us-east-1
|
||||
S3_PREFIX=openreader
|
||||
# Optional (non-AWS S3-compatible providers):
|
||||
# S3_ENDPOINT=https://...
|
||||
# S3_FORCE_PATH_STYLE=true
|
||||
|
||||
# Auth (required for the admin panel)
|
||||
BASE_URL=https://your-app.vercel.app
|
||||
AUTH_SECRET=...
|
||||
ADMIN_EMAILS=you@example.com # comma-separated; admins manage TTS + features in-app
|
||||
|
||||
# First-boot seed for the TTS shared provider (optional; manage in-app afterwards)
|
||||
API_KEY=your_replicate_key
|
||||
# API_BASE only needed for OpenAI-compatible self-hosted providers
|
||||
```
|
||||
|
||||
:::note Env vars vs. admin panel (important for Vercel)
|
||||
`API_KEY` / `API_BASE` are one-shot bootstrap seeds on first deploy. After boot, manage providers and site features in **Settings → Admin**. Changes there apply on refresh without a redeploy. See [Admin Panel](../configure/admin-panel).
|
||||
:::
|
||||
|
||||
## 2. First-run admin configuration (recommended)
|
||||
|
||||
After the first successful deploy and admin login, open **Settings → Admin** and configure:
|
||||
|
||||
- **Shared providers**: create/edit your provider key(s) here (encrypted at rest).
|
||||
- **Site features**:
|
||||
- `enableDocxConversion=false` on Vercel (`soffice` unavailable).
|
||||
- `enableDestructiveDeleteActions=false` for safer public deployments.
|
||||
- `enableTtsProvidersTab=false` if you want shared-provider-only UX.
|
||||
- `enableUserSignups=true` unless you explicitly want an invite-only deployment.
|
||||
- `restrictUserApiKeys=true` to block user BYOK through the hosted server.
|
||||
- `defaultTtsProvider=replicate` (or your preferred shared slug).
|
||||
- `showAllProviderModels=false` if you want users locked to each provider's default model.
|
||||
- `enableAudiobookExport=true`.
|
||||
- `enableWordHighlight=false` unless your timestamp stack is configured.
|
||||
|
||||
## 3. Legacy first-boot seed (optional)
|
||||
|
||||
If you must pre-seed site features via environment variables, the legacy `NEXT_PUBLIC_*` seeds are still supported on first boot only. Prefer the admin panel for ongoing management.
|
||||
|
||||
See [Environment Variables](../reference/environment-variables#legacy-first-boot-runtime-seeds-optional) for the complete legacy seed list.
|
||||
|
||||
:::warning Auth recommendation
|
||||
For internet-exposed Vercel deployments, set both `BASE_URL` and `AUTH_SECRET` — they are also required for the admin panel and for encrypting admin-stored TTS credentials. Running without auth is possible, but not recommended for public environments.
|
||||
:::
|
||||
|
||||
:::warning Rotating AUTH_SECRET invalidates admin-stored keys
|
||||
Admin-managed TTS provider keys are encrypted with a key derived from `AUTH_SECRET`. If you rotate `AUTH_SECRET` after the first deploy, you must re-enter each admin shared provider's API key from the UI.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
For all variables and defaults, see [Environment Variables](../reference/environment-variables).
|
||||
:::
|
||||
|
||||
## 4. Database and data migrations
|
||||
|
||||
Vercel deployments do not run `scripts/openreader-entrypoint.mjs`, so automatic startup migrations do not run there.
|
||||
|
||||
- Run `pnpm migrate` in a controlled environment to apply Drizzle schema migrations to your Postgres DB.
|
||||
- Run `pnpm migrate-fs` only when migrating legacy local filesystem data (`docstore/documents_v1`, `docstore/audiobooks_v1`) into object storage + DB rows. Fresh Vercel deployments usually do not need this.
|
||||
|
||||
## 5. FFmpeg packaging in Vercel functions
|
||||
|
||||
`ffmpeg-static` binaries must be included in function traces. This repo already does that in `next.config.ts` via `outputFileTracingIncludes` for:
|
||||
|
||||
- `/api/audiobook`
|
||||
- `/api/audiobook/chapter`
|
||||
- `/api/audiobook/status`
|
||||
- `/api/whisper`
|
||||
|
||||
:::info
|
||||
`serverExternalPackages` should include `ffmpeg-static` so package paths resolve at runtime instead of being bundled into route output.
|
||||
:::
|
||||
|
||||
If you change route paths or split handlers, update `outputFileTracingIncludes` accordingly.
|
||||
|
||||
## 6. Function memory sizing
|
||||
|
||||
FFmpeg workloads benefit from more memory/CPU. This repo includes:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://openapi.vercel.sh/vercel.json",
|
||||
"functions": {
|
||||
"app/api/audiobook/route.ts": { "memory": 3009 },
|
||||
"app/api/whisper/route.ts": { "memory": 3009 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Adjust memory per route if your files are larger or your plan differs.
|
||||
|
||||
## 7. Runtime expectations and caveats
|
||||
|
||||
- Audiobook APIs require S3 configuration; otherwise they return `503`.
|
||||
- For production Vercel deploys, use `POSTGRES_URL` instead of SQLite.
|
||||
|
||||
## 8. Smoke test after deploy
|
||||
|
||||
1. Upload and read a PDF/EPUB document.
|
||||
2. Confirm sync/blob fetch works across refreshes/devices.
|
||||
3. Generate at least one audiobook chapter and play/download it.
|
||||
4. If using word highlighting, verify timestamps are produced and rendered.
|
||||
157
docs-site/versioned_docs/version-v3.0.0/docker-quick-start.md
Normal file
157
docs-site/versioned_docs/version-v3.0.0/docker-quick-start.md
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
---
|
||||
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](./configure/tts-provider-guides/kokoro-fastapi)
|
||||
- [KittenTTS-FastAPI](./configure/tts-provider-guides/kitten-tts-fastapi)
|
||||
- [Orpheus-FastAPI](./configure/tts-provider-guides/orpheus-fastapi)
|
||||
- [Replicate](./configure/tts-provider-guides/replicate)
|
||||
- [DeepInfra](./configure/tts-provider-guides/deepinfra)
|
||||
- [OpenAI](./configure/tts-provider-guides/openai)
|
||||
- [Other OpenAI-compatible providers](./configure/tts-provider-guides/other)
|
||||
|
||||
:::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
|
||||
|
||||
<Tabs groupId="docker-start-mode">
|
||||
<TabItem value="localhost" label="Localhost" default>
|
||||
|
||||
Persistent storage, embedded SeaweedFS `weed mini`, optional auth, optional library mount:
|
||||
|
||||
```bash
|
||||
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) \
|
||||
-e ADMIN_EMAILS=you@example.com \
|
||||
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=...` / `-e API_KEY=...`: **first-boot seed only.** On the first container start, these are auto-migrated into a `default-openai` admin shared provider stored in the DB (key encrypted at rest). After that, the running app no longer reads them — manage the provider from **Settings → Admin → Shared providers**. See [Admin Panel](./configure/admin-panel).
|
||||
- `-e BASE_URL=...` and `-e AUTH_SECRET=...`: together they turn on auth/session mode for local sign-in flows.
|
||||
- `-e ADMIN_EMAILS=...`: (optional, requires auth) comma-separated emails auto-promoted to admin. Admins see the **Admin** tab in Settings.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="local-network" label="LAN Host">
|
||||
|
||||
Use this when the app should be reachable from other devices on your LAN:
|
||||
|
||||
```bash
|
||||
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 \
|
||||
-e ADMIN_EMAILS=you@example.com \
|
||||
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` seeds the default TTS endpoint into the admin-managed `default-openai` shared provider on first boot. Edit it from **Settings → Admin → Shared providers** after that.
|
||||
- `ADMIN_EMAILS=...` (optional) auto-promotes the listed email(s) to admin so they can manage shared providers and site feature flags from the UI.
|
||||
- `openreader_docstore` volume keeps data persistent across restarts.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="minimal" label="Minimal">
|
||||
|
||||
Auth disabled, embedded storage ephemeral, no library import:
|
||||
|
||||
```bash
|
||||
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. The admin panel requires auth, so it's unavailable in this mode.
|
||||
- No TTS provider preset by default. Configure `API_BASE`/`API_KEY` on first boot if you want a seeded shared provider, or run auth+admin mode and manage providers from the admin panel.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::tip Quick Tips
|
||||
- Set `API_BASE` on first boot to a TTS endpoint the container can reach (`host.docker.internal` works for host-local services). After first boot, manage providers in **Settings → Admin → Shared providers**.
|
||||
- Auth is enabled only when both `BASE_URL` and `AUTH_SECRET` are set. The admin panel requires auth.
|
||||
- Set `ADMIN_EMAILS` to your email if you want the **Admin** tab in Settings.
|
||||
- `restrictUserApiKeys` controls shared-provider-only mode. For per-user BYOK in auth-enabled setups, toggle it off in **Settings → Admin → Site features**. Legacy first-boot seed via `NEXT_PUBLIC_RESTRICT_USER_API_KEYS=false` is still supported.
|
||||
- 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](http://localhost:3003) after startup.
|
||||
|
||||
- If you set `ADMIN_EMAILS`, sign in with that email and open **Settings → Admin** to manage shared TTS providers and site feature flags for all users.
|
||||
- Per-user: set TTS provider/model in **Settings → TTS Provider**. API key/base URL inputs are shown only when `restrictUserApiKeys=false`.
|
||||
- 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.
|
||||
|
||||
```bash
|
||||
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](./reference/environment-variables)
|
||||
- [Auth](./configure/auth)
|
||||
- [Admin Panel](./configure/admin-panel)
|
||||
- [Database](./configure/database)
|
||||
- [Object / Blob Storage](./configure/object-blob-storage)
|
||||
- [Migrations](./configure/migrations)
|
||||
:::
|
||||
53
docs-site/versioned_docs/version-v3.0.0/introduction.md
Normal file
53
docs-site/versioned_docs/version-v3.0.0/introduction.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
id: intro
|
||||
title: Introduction
|
||||
slug: /
|
||||
---
|
||||
|
||||
OpenReader is an open source text-to-speech document reader built with Next.js. It provides a read-along experience with narration for **EPUB, PDF, TXT, MD, and DOCX documents**.
|
||||
|
||||
> Previously named **OpenReader-WebUI**.
|
||||
|
||||
It supports multiple TTS providers including OpenAI, Replicate, DeepInfra, and custom OpenAI-compatible endpoints such as [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI), [KittenTTS-FastAPI](https://github.com/richardr1126/KittenTTS-FastAPI), and [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI).
|
||||
|
||||
## ✨ Highlights
|
||||
|
||||
- 🎯 **Multi-Provider TTS Support**
|
||||
- [**Kokoro-FastAPI**](https://github.com/remsky/Kokoro-FastAPI): supports multi-voice combinations (for example `af_heart+af_bella`)
|
||||
- [**KittenTTS-FastAPI**](https://github.com/richardr1126/KittenTTS-FastAPI): lightweight, CPU-friendly self-hosted TTS
|
||||
- [**Orpheus-FastAPI**](https://github.com/Lex-au/Orpheus-FastAPI)
|
||||
- **Custom OpenAI-compatible**: any TTS API with `/v1/audio/voices` and `/v1/audio/speech` endpoints
|
||||
- **Cloud TTS providers**:
|
||||
- [**Replicate**](https://replicate.com/explore): includes a built-in catalog and supports any Replicate model ID via `Other`
|
||||
- [**DeepInfra**](https://deepinfra.com/models/text-to-speech): Kokoro-82M and other hosted models
|
||||
- [**OpenAI API**](https://platform.openai.com/docs/pricing#transcription-and-speech): `tts-1`, `tts-1-hd`, and `gpt-4o-mini-tts`
|
||||
- 📖 **Read Along Experience**
|
||||
- Real-time highlighting for PDF/EPUB, with optional word-level [whisper.cpp](https://github.com/ggml-org/whisper.cpp) timestamps
|
||||
- 🛜 **Document Storage**
|
||||
- Documents are persisted in server blob/object storage for consistent access
|
||||
- ⚡ **Segment-based TTS Playback** for reusable generation + preloading
|
||||
- Stores segment audio in object storage for fast replay/resume
|
||||
- 🎧 **Audiobook Export** in `m4b`/`mp3` with resumable chapter generation
|
||||
- 🔐 **Auth Optional by Design**
|
||||
- Run no-auth for local use, or enable auth with user isolation and claim flow
|
||||
- 🗂️ **Flexible Storage and Database Modes** with embedded defaults or external S3/Postgres
|
||||
- 🚀 **Production-ready Server Behavior** with TTS caching/retries/rate limits and startup migrations
|
||||
- 🎨 **Customizable Experience**
|
||||
- 13 built-in themes (light and dark palettes), TTS, and document handling controls
|
||||
|
||||
## 🧭 Key Docs
|
||||
|
||||
- [Docker Quick Start](./docker-quick-start)
|
||||
- [Local Development](./deploy/local-development)
|
||||
- [Vercel Deployment](./deploy/vercel-deployment)
|
||||
- [Environment Variables](./reference/environment-variables)
|
||||
- [Auth](./configure/auth)
|
||||
- [Database](./configure/database)
|
||||
- [Object / Blob Storage](./configure/object-blob-storage)
|
||||
- [Migrations](./configure/migrations)
|
||||
- [Server Library Import](./configure/server-library-import)
|
||||
- [TTS Providers](./configure/tts-providers)
|
||||
|
||||
## Source Repository
|
||||
|
||||
- GitHub: [richardr1126/openreader](https://github.com/richardr1126/openreader)
|
||||
|
|
@ -0,0 +1,445 @@
|
|||
---
|
||||
title: Environment Variables
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
This is the single reference page for OpenReader environment variables.
|
||||
|
||||
:::note Recommended configuration path
|
||||
For auth-enabled deployments, use **Settings → Admin** as the primary source of truth for shared TTS providers and site features. Legacy env vars (`API_KEY`, `API_BASE`, and `NEXT_PUBLIC_*`) are optional first-boot seeds only.
|
||||
:::
|
||||
|
||||
## Quick Reference Table
|
||||
|
||||
| Variable | Area | Default | When to set |
|
||||
| --- | --- | --- | --- |
|
||||
| `ADMIN_EMAILS` | Auth/Admin | empty | Comma-separated emails auto-promoted to admin (requires auth enabled) |
|
||||
| `API_BASE` | Legacy bootstrap seed | none | Optional first-boot seed into `default-openai`; then manage in Settings → Admin → Shared providers |
|
||||
| `API_KEY` | Legacy bootstrap seed | none | Optional first-boot seed into `default-openai`; then manage in Settings → Admin → Shared providers |
|
||||
| `NEXT_PUBLIC_*` runtime seeds | Legacy bootstrap seed | varies | Optional first-boot seeds for site features; then manage in Settings → Admin → Site features |
|
||||
| `NEXT_PUBLIC_CHANGELOG_FEED_URL` | Legacy bootstrap seed | `https://docs.openreader.richardr.dev/changelog/manifest.json` | Optional first-boot seed for changelog feed URL; then manage in Settings → Admin → Site features |
|
||||
| `NEXT_PUBLIC_ENABLE_USER_SIGNUPS` | Legacy bootstrap seed | `true` | Optional first-boot seed for whether new accounts can be created; then manage in Settings → Admin → Site features |
|
||||
| `TTS_CACHE_MAX_SIZE_BYTES` | TTS caching | `268435456` (256 MB) | Tune in-memory TTS cache size |
|
||||
| `TTS_CACHE_TTL_MS` | TTS caching | `1800000` (30 min) | Tune in-memory TTS cache TTL |
|
||||
| `TTS_MAX_RETRIES` | TTS retry | `2` | Tune retry attempts for upstream 429/5xx |
|
||||
| `TTS_RETRY_INITIAL_MS` | TTS retry | `250` | Tune initial retry delay |
|
||||
| `TTS_RETRY_MAX_MS` | TTS retry | `2000` | Tune max retry delay |
|
||||
| `TTS_RETRY_BACKOFF` | TTS retry | `2` | Tune exponential backoff factor |
|
||||
| `TTS_UPSTREAM_TIMEOUT_MS` | TTS request timeout | `285000` | Set max upstream TTS request duration before fail-fast |
|
||||
| `TTS_ENABLE_RATE_LIMIT` | Rate limiting | `false` | Set `true` to enable TTS per-user/IP daily character limits |
|
||||
| `TTS_DAILY_LIMIT_ANONYMOUS` | Rate limiting | `50000` | Override anonymous per-user daily character limit |
|
||||
| `TTS_DAILY_LIMIT_AUTHENTICATED` | Rate limiting | `500000` | Override authenticated per-user daily character limit |
|
||||
| `TTS_IP_DAILY_LIMIT_ANONYMOUS` | Rate limiting | `100000` | Override anonymous IP backstop daily limit |
|
||||
| `TTS_IP_DAILY_LIMIT_AUTHENTICATED` | Rate limiting | `1000000` | Override authenticated IP backstop daily limit |
|
||||
| `BASE_URL` | Auth | unset | Required (with `AUTH_SECRET`) to enable auth |
|
||||
| `AUTH_SECRET` | Auth | unset | Required (with `BASE_URL`) to enable auth |
|
||||
| `AUTH_TRUSTED_ORIGINS` | Auth | empty | Add extra allowed origins |
|
||||
| `USE_ANONYMOUS_AUTH_SESSIONS` | Auth | `false` | Set `true` to enable anonymous auth sessions |
|
||||
| `GITHUB_CLIENT_ID` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_SECRET` to enable GitHub sign-in |
|
||||
| `GITHUB_CLIENT_SECRET` | Auth/OAuth | unset | Set with `GITHUB_CLIENT_ID` to enable GitHub sign-in |
|
||||
| `DISABLE_AUTH_RATE_LIMIT` | Rate limiting | `false` | Set `true` to disable auth-layer rate limiting |
|
||||
| `POSTGRES_URL` | Database | unset (SQLite mode) | Set to switch metadata/auth DB to Postgres |
|
||||
| `USE_EMBEDDED_WEED_MINI` | Storage | `true` when unset | Set `false` to use external S3-compatible storage only |
|
||||
| `WEED_MINI_DIR` | Storage | `docstore/seaweedfs` | Override embedded SeaweedFS data directory |
|
||||
| `WEED_MINI_WAIT_SEC` | Storage | `20` | Tune SeaweedFS startup wait timeout |
|
||||
| `S3_ACCESS_KEY_ID` | Storage | auto-generated in embedded mode | Set explicitly for stable/external credentials |
|
||||
| `S3_SECRET_ACCESS_KEY` | Storage | auto-generated in embedded mode | Set explicitly for stable/external credentials |
|
||||
| `S3_BUCKET` | Storage | `openreader-documents` in embedded mode | Required for external S3-compatible storage |
|
||||
| `S3_REGION` | Storage | `us-east-1` in embedded mode | Required for external S3-compatible storage |
|
||||
| `S3_ENDPOINT` | Storage | derived in embedded mode | Set for S3-compatible providers (MinIO/SeaweedFS/R2/etc.) |
|
||||
| `S3_FORCE_PATH_STYLE` | Storage | `true` in embedded mode | Set per provider requirement |
|
||||
| `S3_PREFIX` | Storage | `openreader` | Customize object key prefix |
|
||||
| `RUN_DRIZZLE_MIGRATIONS` | Database migrations | `true` | Set `false` to skip startup Drizzle schema migrations |
|
||||
| `RUN_FS_MIGRATIONS` | Storage migrations | `true` | Set `false` to skip startup filesystem -> S3/DB migration pass |
|
||||
| `IMPORT_LIBRARY_DIR` | Library import | `docstore/library` fallback | Set a single server library root |
|
||||
| `IMPORT_LIBRARY_DIRS` | Library import | unset | Set multiple roots (comma/colon/semicolon separated) |
|
||||
| `WHISPER_CPP_BIN` | Word timing | unset | Set to enable `whisper.cpp` timestamps |
|
||||
| `FFMPEG_BIN` | Audio runtime | auto-detected (`ffmpeg-static`) | Override ffmpeg binary path |
|
||||
|
||||
|
||||
|
||||
## TTS Provider and Request Behavior
|
||||
|
||||
### API_BASE
|
||||
|
||||
Bootstrap base URL for the legacy OpenAI-compatible TTS endpoint.
|
||||
|
||||
- Example: `http://host.docker.internal:8880/v1`
|
||||
- **Seeded on first boot** into the auto-created `default-openai` shared provider, then no longer read by the running app. Manage in **Settings → Admin → Shared providers** afterwards.
|
||||
- Related docs: [Admin Panel](../configure/admin-panel), [TTS Providers](../configure/tts-providers)
|
||||
|
||||
### API_KEY
|
||||
|
||||
Bootstrap API key for the legacy OpenAI-compatible TTS endpoint.
|
||||
|
||||
- Example: your provider token, or omit if the provider doesn't require auth
|
||||
- **Seeded on first boot** into the auto-created `default-openai` shared provider (encrypted at rest), then no longer read by the running app. Manage in **Settings → Admin → Shared providers** afterwards.
|
||||
- Related docs: [Admin Panel](../configure/admin-panel), [TTS Providers](../configure/tts-providers)
|
||||
|
||||
### TTS_CACHE_MAX_SIZE_BYTES
|
||||
|
||||
Maximum in-memory TTS audio cache size in bytes.
|
||||
|
||||
- Default: `268435456` (256 MB)
|
||||
|
||||
### TTS_CACHE_TTL_MS
|
||||
|
||||
In-memory TTS audio cache TTL in milliseconds.
|
||||
|
||||
- Default: `1800000` (30 minutes)
|
||||
|
||||
### TTS_MAX_RETRIES
|
||||
|
||||
Maximum retries for upstream TTS failures (429/5xx).
|
||||
|
||||
- Default: `2`
|
||||
|
||||
### TTS_RETRY_INITIAL_MS
|
||||
|
||||
Initial retry delay in milliseconds for TTS upstream requests.
|
||||
|
||||
- Default: `250`
|
||||
|
||||
### TTS_RETRY_MAX_MS
|
||||
|
||||
Maximum retry delay in milliseconds.
|
||||
|
||||
- Default: `2000`
|
||||
|
||||
### TTS_RETRY_BACKOFF
|
||||
|
||||
Exponential backoff multiplier between retries.
|
||||
|
||||
- Default: `2`
|
||||
|
||||
### TTS_UPSTREAM_TIMEOUT_MS
|
||||
|
||||
Maximum upstream TTS request timeout in milliseconds.
|
||||
|
||||
- Default: `285000` (285 seconds)
|
||||
- Applies to outbound provider calls from server routes using shared TTS generation
|
||||
- Increase for slower providers/models; decrease to fail fast and surface retryable errors sooner
|
||||
|
||||
### TTS_ENABLE_RATE_LIMIT
|
||||
|
||||
Controls TTS character rate limiting in the TTS API.
|
||||
|
||||
- Default: `false` (TTS char limits disabled)
|
||||
- Set to `true` to enforce `TTS_DAILY_LIMIT_*` and `TTS_IP_DAILY_LIMIT_*`
|
||||
- For behavior details and examples, see [TTS Rate Limiting](../configure/tts-rate-limiting)
|
||||
|
||||
### TTS_DAILY_LIMIT_ANONYMOUS
|
||||
|
||||
Anonymous per-user daily character limit.
|
||||
|
||||
- Default: `50000`
|
||||
|
||||
### TTS_DAILY_LIMIT_AUTHENTICATED
|
||||
|
||||
Authenticated per-user daily character limit.
|
||||
|
||||
- Default: `500000`
|
||||
|
||||
### TTS_IP_DAILY_LIMIT_ANONYMOUS
|
||||
|
||||
Anonymous IP backstop daily character limit.
|
||||
|
||||
- Default: `100000`
|
||||
|
||||
### TTS_IP_DAILY_LIMIT_AUTHENTICATED
|
||||
|
||||
Authenticated IP backstop daily character limit.
|
||||
|
||||
- Default: `1000000`
|
||||
|
||||
## Auth and Identity
|
||||
|
||||
### BASE_URL
|
||||
|
||||
External base URL for this OpenReader instance.
|
||||
|
||||
- Required with `AUTH_SECRET` to enable auth
|
||||
- Example: `http://localhost:3003` or `https://reader.example.com`
|
||||
- Related docs: [Auth](../configure/auth)
|
||||
|
||||
### AUTH_SECRET
|
||||
|
||||
Secret key used by auth/session handling.
|
||||
|
||||
- Required with `BASE_URL` to enable auth
|
||||
- Generate with `openssl rand -hex 32`
|
||||
- Also used to HMAC-hash server-side TTS segment text fingerprints
|
||||
- Related docs: [Auth](../configure/auth)
|
||||
|
||||
### AUTH_TRUSTED_ORIGINS
|
||||
|
||||
Additional allowed origins for auth requests.
|
||||
|
||||
- Comma-separated list
|
||||
- `BASE_URL` origin is always trusted automatically
|
||||
- Related docs: [Auth](../configure/auth)
|
||||
|
||||
### USE_ANONYMOUS_AUTH_SESSIONS
|
||||
|
||||
Controls whether auth-enabled deployments can create/use anonymous sessions.
|
||||
|
||||
- Default: `false` (anonymous sessions disabled)
|
||||
- Set `true` to allow anonymous sessions and guest-style flows
|
||||
- When `false`, users must sign in or sign up with an account
|
||||
- Related docs: [Auth](../configure/auth)
|
||||
|
||||
### GITHUB_CLIENT_ID
|
||||
|
||||
GitHub OAuth client ID.
|
||||
|
||||
- Enable only with `GITHUB_CLIENT_SECRET`
|
||||
|
||||
### GITHUB_CLIENT_SECRET
|
||||
|
||||
GitHub OAuth client secret.
|
||||
|
||||
- Enable only with `GITHUB_CLIENT_ID`
|
||||
|
||||
### DISABLE_AUTH_RATE_LIMIT
|
||||
|
||||
Controls Better Auth rate limiting.
|
||||
|
||||
- Default behavior: auth-layer rate limiting enabled
|
||||
- Set to `true` to disable auth-layer rate limiting
|
||||
- This does not affect TTS character rate limiting
|
||||
- Related docs: [Auth](../configure/auth)
|
||||
|
||||
### ADMIN_EMAILS
|
||||
|
||||
Comma-separated list of email addresses that are auto-promoted to admin.
|
||||
|
||||
- Default: empty (no admins)
|
||||
- Requires auth to be enabled (`AUTH_SECRET` + `BASE_URL`).
|
||||
- Matched emails get `user.is_admin = true` on every session resolution; removed emails are demoted on the next session resolve.
|
||||
- Admins see a new **Admin** tab in Settings exposing shared TTS providers and site-wide feature toggles. Keys for shared providers are stored encrypted in the DB and never returned to the client.
|
||||
- Example: `ADMIN_EMAILS=alice@example.com,bob@example.com`
|
||||
- Related docs: [Admin Panel](../configure/admin-panel), [Auth](../configure/auth)
|
||||
|
||||
## Database and Object Blob Storage
|
||||
|
||||
### POSTGRES_URL
|
||||
|
||||
Switches metadata/auth storage from SQLite to Postgres.
|
||||
|
||||
- Unset: SQLite at `docstore/sqlite3.db`
|
||||
- Set: Postgres mode
|
||||
- Related docs: [Database](../configure/database)
|
||||
|
||||
### USE_EMBEDDED_WEED_MINI
|
||||
|
||||
Controls embedded SeaweedFS startup.
|
||||
|
||||
- Default behavior: treated as enabled when unset
|
||||
- Set `false` to rely on external S3-compatible storage
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### WEED_MINI_DIR
|
||||
|
||||
Data directory for embedded SeaweedFS (`weed mini`).
|
||||
|
||||
- Default: `docstore/seaweedfs`
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### WEED_MINI_WAIT_SEC
|
||||
|
||||
Maximum seconds to wait for embedded SeaweedFS startup.
|
||||
|
||||
- Default: `20`
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### S3_ACCESS_KEY_ID
|
||||
|
||||
Access key for S3-compatible storage.
|
||||
|
||||
- Auto-generated in embedded mode if unset
|
||||
- Set explicitly for stable credentials or external providers
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### S3_SECRET_ACCESS_KEY
|
||||
|
||||
Secret key for S3-compatible storage.
|
||||
|
||||
- Auto-generated in embedded mode if unset
|
||||
- Set explicitly for stable credentials or external providers
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### S3_BUCKET
|
||||
|
||||
Bucket name used for document blobs.
|
||||
|
||||
- Default in embedded mode: `openreader-documents`
|
||||
- Required for external S3-compatible storage
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### S3_REGION
|
||||
|
||||
Region used by the S3 client.
|
||||
|
||||
- Default in embedded mode: `us-east-1`
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### S3_ENDPOINT
|
||||
|
||||
Endpoint URL for S3-compatible storage.
|
||||
|
||||
- In embedded mode, defaults to `http://<BASE_URL host>:8333` (or detected host)
|
||||
- For AWS S3, usually leave unset
|
||||
- For MinIO/SeaweedFS/R2/B2-style APIs, typically set explicitly
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### S3_FORCE_PATH_STYLE
|
||||
|
||||
Path-style S3 addressing toggle.
|
||||
|
||||
- Default in embedded mode: `true`
|
||||
- Set according to provider requirements
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
### S3_PREFIX
|
||||
|
||||
Prefix prepended to stored object keys.
|
||||
|
||||
- Default: `openreader`
|
||||
- Related docs: [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
## Migration Controls
|
||||
|
||||
### RUN_DRIZZLE_MIGRATIONS
|
||||
|
||||
Controls startup migration execution in shared entrypoint.
|
||||
|
||||
- Default: `true`
|
||||
- Set `false` to skip automatic startup Drizzle schema migrations
|
||||
- Related docs: [Migrations](../configure/migrations), [Database](../configure/database)
|
||||
|
||||
### RUN_FS_MIGRATIONS
|
||||
|
||||
Controls startup filesystem-to-object-store migration execution in shared entrypoint.
|
||||
|
||||
- Default: `true`
|
||||
- Runs `scripts/migrate-fs-v2.mjs` at startup after DB migrations
|
||||
- Set `false` to skip automatic storage migration pass
|
||||
- Related docs: [Migrations](../configure/migrations), [Database](../configure/database), [Object / Blob Storage](../configure/object-blob-storage)
|
||||
|
||||
## Library Import
|
||||
|
||||
### IMPORT_LIBRARY_DIR
|
||||
|
||||
Single directory root for server library import.
|
||||
|
||||
- Used when `IMPORT_LIBRARY_DIRS` is unset
|
||||
- Default fallback root: `docstore/library`
|
||||
- Related docs: [Server Library Import](../configure/server-library-import)
|
||||
|
||||
### IMPORT_LIBRARY_DIRS
|
||||
|
||||
Multiple library roots for server library import.
|
||||
|
||||
- Separator: comma, colon, or semicolon
|
||||
- Takes precedence over `IMPORT_LIBRARY_DIR`
|
||||
- Related docs: [Server Library Import](../configure/server-library-import)
|
||||
|
||||
## Audio Tooling and Alignment
|
||||
|
||||
### WHISPER_CPP_BIN
|
||||
|
||||
Absolute path to compiled `whisper.cpp` binary for word-level timestamps.
|
||||
|
||||
- Example: `/whisper.cpp/build/bin/whisper-cli`
|
||||
- Required only for optional word-by-word highlighting
|
||||
|
||||
### FFMPEG_BIN
|
||||
|
||||
Absolute path or executable name for the ffmpeg binary used by audiobook/processing routes.
|
||||
|
||||
- Resolution order: `FFMPEG_BIN` -> `ffmpeg-static`
|
||||
- Example: `/var/task/node_modules/ffmpeg-static/ffmpeg`
|
||||
|
||||
## Legacy First-Boot Runtime Seeds (optional)
|
||||
|
||||
These variables exist only as **first-boot seeds** for the admin-managed runtime config. Prefer changing site features from **Settings → Admin → Site features**. Keep these only when you need bootstrap defaults before the first admin login. See [Admin Panel](../configure/admin-panel) for migration behavior.
|
||||
|
||||
The values are SSR-injected via `window.__OPENREADER_RUNTIME_CONFIG__`, so admin edits take effect for all users on the next page load — no rebuild required (unlike the old `NEXT_PUBLIC_*` build-time pattern).
|
||||
|
||||
### NEXT_PUBLIC_ENABLE_DOCX_CONVERSION
|
||||
|
||||
Controls whether the experimental DOCX-to-PDF conversion and upload feature is enabled.
|
||||
|
||||
- Default: `true` (enabled)
|
||||
- Runtime key: `enableDocxConversion`
|
||||
|
||||
### NEXT_PUBLIC_ENABLE_DESTRUCTIVE_DELETE_ACTIONS
|
||||
|
||||
Controls whether the "Delete all user docs" and other bulk-delete buttons are shown in Settings.
|
||||
|
||||
- Default: `true` (enabled)
|
||||
- Runtime key: `enableDestructiveDeleteActions`
|
||||
|
||||
### NEXT_PUBLIC_ENABLE_TTS_PROVIDERS_TAB
|
||||
|
||||
Controls whether the **TTS Provider** section appears in the user-facing Settings modal.
|
||||
|
||||
- Default: `true` (enabled)
|
||||
- Set `false` to hide provider/model/API controls in the per-user Settings modal (the admin panel is unaffected).
|
||||
- Runtime key: `enableTtsProvidersTab`
|
||||
|
||||
### NEXT_PUBLIC_ENABLE_USER_SIGNUPS
|
||||
|
||||
Controls whether new user accounts can be created.
|
||||
|
||||
- Default: `true` (enabled)
|
||||
- When `false`, new account creation is blocked for email sign-up, first-time OAuth signup, and anonymous-to-account upgrades.
|
||||
- Existing users can still sign in.
|
||||
- Runtime key: `enableUserSignups`
|
||||
|
||||
### NEXT_PUBLIC_RESTRICT_USER_API_KEYS
|
||||
|
||||
Controls whether users can supply personal API keys/base URLs for built-in providers.
|
||||
|
||||
- Default: runtime-dependent
|
||||
- When `true`, server routes only use admin-managed shared providers.
|
||||
- When `false`, users can use per-user BYOK credentials for built-in providers.
|
||||
- Runtime key: `restrictUserApiKeys`
|
||||
|
||||
### NEXT_PUBLIC_DEFAULT_TTS_PROVIDER
|
||||
|
||||
Sets the default TTS provider for new users.
|
||||
|
||||
- Default: `custom-openai`
|
||||
- Example values: `replicate`, `deepinfra`, `openai`, `custom-openai`, or an admin-defined shared provider slug (e.g. `kokoro-prod`)
|
||||
- Runtime key: `defaultTtsProvider`
|
||||
|
||||
`showAllProviderModels` is a runtime-only admin setting (no env seed). Configure it in **Settings → Admin → Site features**.
|
||||
|
||||
### NEXT_PUBLIC_CHANGELOG_FEED_URL
|
||||
|
||||
Sets the changelog manifest URL used by the Settings modal changelog viewer.
|
||||
|
||||
- Default: `https://docs.openreader.richardr.dev/changelog/manifest.json`
|
||||
- Use this in self-hosted deployments when you publish changelog feeds to a custom docs domain/path.
|
||||
- Runtime key: `changelogFeedUrl`
|
||||
|
||||
|
||||
### NEXT_PUBLIC_ENABLE_AUDIOBOOK_EXPORT
|
||||
|
||||
Controls whether audiobook export UI/actions are shown in the client.
|
||||
|
||||
- Default: `true` (enabled)
|
||||
- Affects export entry points in PDF/EPUB pages and document settings UI
|
||||
- Runtime key: `enableAudiobookExport`
|
||||
|
||||
### NEXT_PUBLIC_ENABLE_WORD_HIGHLIGHT
|
||||
|
||||
Controls word-by-word highlighting UI and timestamp-alignment behavior.
|
||||
|
||||
- Default: `true` (enabled)
|
||||
- Requires working timestamp generation (for example `WHISPER_CPP_BIN`)
|
||||
- Affects:
|
||||
- Word-highlight toggles in document settings
|
||||
- Alignment requests during TTS playback
|
||||
- Runtime key: `enableWordHighlight`
|
||||
44
docs-site/versioned_docs/version-v3.0.0/reference/stack.md
Normal file
44
docs-site/versioned_docs/version-v3.0.0/reference/stack.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Stack
|
||||
---
|
||||
|
||||
## Framework
|
||||
|
||||
- [Next.js](https://nextjs.org/) 15 (App Router)
|
||||
- [React](https://react.dev/) 19
|
||||
- [TypeScript](https://www.typescriptlang.org/)
|
||||
|
||||
## Containerization and runtime
|
||||
|
||||
- [Docker](https://www.docker.com/) (linux/amd64 and linux/arm64)
|
||||
- Shared entrypoint that runs DB migrations by default and can bootstrap embedded SeaweedFS before app startup
|
||||
|
||||
## Next.js client
|
||||
|
||||
- UI: [Tailwind CSS](https://tailwindcss.com), [Headless UI](https://headlessui.com), [@tailwindcss/typography](https://tailwindcss.com/docs/typography-plugin)
|
||||
- Interactions: `react-dnd`, `react-dropzone`
|
||||
- Authentication: [Better Auth](https://www.better-auth.com/) client SDK
|
||||
- Local storage/cache: [Dexie.js](https://dexie.org/) (IndexedDB)
|
||||
- Document rendering:
|
||||
- PDF: [react-pdf](https://github.com/wojtekmaj/react-pdf), [pdf.js](https://mozilla.github.io/pdf.js/)
|
||||
- EPUB: [react-reader](https://github.com/gerhardsletten/react-reader), [epubjs](https://github.com/futurepress/epub.js/)
|
||||
- Markdown/Text: [react-markdown](https://github.com/remarkjs/react-markdown), [remark-gfm](https://github.com/remarkjs/remark-gfm)
|
||||
- Text preprocessing/matching: [compromise](https://github.com/spencermountain/compromise), [cmpstr](https://github.com/remsky/cmpstr)
|
||||
|
||||
## Next.js server
|
||||
|
||||
- APIs: Route Handlers for sync, blob/content access, migrations, audiobook export, TTS/Whisper proxying
|
||||
- State sync: request-based today (not realtime push updates)
|
||||
- Authentication: [Better Auth](https://www.better-auth.com/) server handlers/adapters
|
||||
- Metadata DB: [Drizzle ORM](https://orm.drizzle.team/) with SQLite (`better-sqlite3`) by default and optional Postgres (`pg`)
|
||||
- App tables are manually maintained in Drizzle schema files
|
||||
- Auth tables are auto-generated by the [Better Auth](https://www.better-auth.com/) CLI and migrated alongside app tables via Drizzle
|
||||
- Blob storage: embedded [SeaweedFS](https://github.com/seaweedfs/seaweedfs) (`weed mini`) by default, or external S3-compatible storage via AWS SDK v3
|
||||
- Audio/processing pipeline: OpenAI-compatible TTS providers, [ffmpeg](https://ffmpeg.org/) for audiobook assembly, optional [whisper.cpp](https://github.com/ggerganov/whisper.cpp) for word timestamps
|
||||
|
||||
## Tooling and testing
|
||||
|
||||
- ESLint
|
||||
- TypeScript
|
||||
- [Playwright](https://playwright.dev/) end-to-end tests
|
||||
- Drizzle migration/generation scripts
|
||||
77
docs-site/versioned_sidebars/version-v3.0.0-sidebars.json
Normal file
77
docs-site/versioned_sidebars/version-v3.0.0-sidebars.json
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
{
|
||||
"tutorialSidebar": [
|
||||
"intro",
|
||||
{
|
||||
"type": "doc",
|
||||
"id": "docker-quick-start",
|
||||
"label": "🐳 Docker Quick Start"
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "⚙️ Configure",
|
||||
"items": [
|
||||
{
|
||||
"type": "category",
|
||||
"label": "🔊 TTS Providers",
|
||||
"link": {
|
||||
"type": "doc",
|
||||
"id": "configure/tts-providers"
|
||||
},
|
||||
"items": [
|
||||
"configure/tts-provider-guides/kokoro-fastapi",
|
||||
"configure/tts-provider-guides/kitten-tts-fastapi",
|
||||
"configure/tts-provider-guides/orpheus-fastapi",
|
||||
"configure/tts-provider-guides/replicate",
|
||||
"configure/tts-provider-guides/deepinfra",
|
||||
"configure/tts-provider-guides/openai",
|
||||
"configure/tts-provider-guides/other"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "doc",
|
||||
"id": "configure/auth",
|
||||
"label": "🔐 Auth"
|
||||
},
|
||||
{
|
||||
"type": "doc",
|
||||
"id": "configure/admin-panel",
|
||||
"label": "🛡️ Admin Panel"
|
||||
},
|
||||
{
|
||||
"type": "doc",
|
||||
"id": "configure/server-library-import",
|
||||
"label": "📥 Server Library Import"
|
||||
},
|
||||
"configure/tts-rate-limiting",
|
||||
"configure/database",
|
||||
"configure/object-blob-storage",
|
||||
"configure/migrations"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "🚀 Deploy",
|
||||
"items": [
|
||||
"deploy/local-development",
|
||||
"deploy/vercel-deployment"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "Reference",
|
||||
"items": [
|
||||
"reference/environment-variables",
|
||||
"reference/stack"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "About",
|
||||
"items": [
|
||||
"about/support-and-contributing",
|
||||
"about/acknowledgements",
|
||||
"about/license"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
[
|
||||
"v3.0.0",
|
||||
"v2.2.0",
|
||||
"v2.1.2",
|
||||
"v2.1.1",
|
||||
|
|
|
|||
Loading…
Reference in a new issue