diff --git a/docs-site/docs/configure/configuration.md b/docs-site/docs/configure/auth.md similarity index 88% rename from docs-site/docs/configure/configuration.md rename to docs-site/docs/configure/auth.md index 9e84114..0e8d9df 100644 --- a/docs-site/docs/configure/configuration.md +++ b/docs-site/docs/configure/auth.md @@ -15,5 +15,5 @@ This page covers application-level configuration for provider access and authent - For the complete variable reference: [Environment Variables](../reference/environment-variables) - 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](./storage-and-blob-behavior) +- For storage/S3/SeaweedFS behavior: [Object / Blob Storage](./object-blob-storage) - For database mode and migration commands: [Database and Migrations](./database-and-migrations) diff --git a/docs-site/docs/configure/database-and-migrations.md b/docs-site/docs/configure/database-and-migrations.md index 50bc434..1f89edd 100644 --- a/docs-site/docs/configure/database-and-migrations.md +++ b/docs-site/docs/configure/database-and-migrations.md @@ -2,12 +2,15 @@ title: Database and Migrations --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + This page covers database mode selection and migration behavior for OpenReader WebUI. ## Database mode -- Default mode: embedded SQLite at `docstore/sqlite3.db` -- External mode: Postgres when `POSTGRES_URL` is set +- 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. ## Startup migration behavior @@ -22,6 +25,10 @@ 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. +::: + To skip automatic startup migrations: - Set `RUN_DRIZZLE_MIGRATIONS=false` @@ -33,6 +40,9 @@ Database variables are documented in [Environment Variables](../reference/enviro In most cases, you do not need manual migration commands because startup runs migrations automatically. + + + ```bash # Run pending migrations (uses Postgres config when POSTGRES_URL is set, otherwise SQLite) pnpm migrate @@ -47,7 +57,8 @@ pnpm migrate-fs:dry-run pnpm generate ``` -## Manual Drizzle commands (advanced) + + ```bash # Migrate SQLite @@ -62,3 +73,10 @@ pnpm exec drizzle-kit generate --config drizzle.config.sqlite.ts # Generate Postgres migrations pnpm exec drizzle-kit generate --config drizzle.config.pg.ts ``` + + + + +:::warning +If you disable startup migrations, ensure your deployment process runs migrations before serving traffic. +::: diff --git a/docs-site/docs/configure/storage-and-blob-behavior.md b/docs-site/docs/configure/object-blob-storage.md similarity index 59% rename from docs-site/docs/configure/storage-and-blob-behavior.md rename to docs-site/docs/configure/object-blob-storage.md index f437ce9..2aad353 100644 --- a/docs-site/docs/configure/storage-and-blob-behavior.md +++ b/docs-site/docs/configure/object-blob-storage.md @@ -2,12 +2,12 @@ title: Object / Blob Storage --- -This page documents storage backends, blob upload routing, and Docker mount behavior. +This page documents storage backends, blob upload routing, and core Docker mount behavior. ## Storage backends -- Default: embedded SQLite metadata + embedded SeaweedFS (`weed mini`) blobs -- External option: Postgres + external S3-compatible object storage +- Embedded (default): SQLite metadata + embedded SeaweedFS (`weed mini`) blobs. +- External: Postgres + external S3-compatible object storage. Storage variables are documented in [Environment Variables](../reference/environment-variables) under the storage sections. @@ -16,24 +16,23 @@ Storage variables are documented in [Environment Variables](../reference/environ - `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` if direct upload fails or endpoint is unreachable -- Content serving path: `/api/documents/blob` +- 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). ## Recommended Docker mounts | Mount | Type | Recommended | Purpose | Example | | --- | --- | --- | --- | --- | | `/app/docstore` | Docker named volume | Yes (for persistence) | Persists SeaweedFS blob data, SQLite metadata DB, migrations, and local runtime temp state | `-v openreader_docstore:/app/docstore` | -| `/app/docstore/library` | Bind mount | Optional + `:ro` | Read-only source for server library import (files are copied/imported into client storage) | `-v /path/to/your/library:/app/docstore/library:ro` | -To import from mounted library: **Settings -> Documents -> Server Library Import**. - -:::note -Every file in the mounted library is imported into client browser storage. Keep the library reasonably sized. -::: +For server library mounts/import behavior, see [Server Library Import](./server-library-import). ## Private blob endpoint mode @@ -43,6 +42,10 @@ If `8333` is not published externally: - 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 note - In current versions, audiobook assets live in object storage (`audiobooks_v1` keyspace), not as durable files under `/app/docstore`. diff --git a/docs-site/docs/configure/server-library-import.md b/docs-site/docs/configure/server-library-import.md new file mode 100644 index 0000000..9301fa3 --- /dev/null +++ b/docs-site/docs/configure/server-library-import.md @@ -0,0 +1,66 @@ +--- +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 + +## Configure library roots + +Library roots are resolved from environment variables: + +- `IMPORT_LIBRARY_DIRS` (takes precedence): multiple roots separated by comma, colon, or semicolon +- `IMPORT_LIBRARY_DIR`: single root +- Fallback when neither is set: `docstore/library` + +See [Environment Variables](../reference/environment-variables#import_library_dir) for details. + +## Docker mount example + +Mount a host folder to the default library path: + +```bash +docker run --name openreader-webui \ + --restart unless-stopped \ + -p 3003:3003 \ + -v openreader_docstore:/app/docstore \ + -v /path/to/your/library:/app/docstore/library:ro \ + ghcr.io/richardr1126/openreader-webui:latest +``` + +Using `:ro` is recommended so the app treats the library as a read-only source. + +## 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` + +## 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. diff --git a/docs-site/docs/configure/tts-providers.md b/docs-site/docs/configure/tts-providers.md index 8351ff2..e5b41df 100644 --- a/docs-site/docs/configure/tts-providers.md +++ b/docs-site/docs/configure/tts-providers.md @@ -2,47 +2,75 @@ title: TTS Providers --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + OpenReader WebUI supports OpenAI-compatible TTS providers through a common API shape. -## Supported provider patterns +:::tip +If you are running a self-hosted TTS server (Kokoro/Orpheus/etc.), use **Custom OpenAI-Like** in Settings. +::: -- OpenAI API -- DeepInfra -- Kokoro-FastAPI -- Orpheus-FastAPI -- Custom OpenAI-compatible endpoints +## Quick Setup by Provider -## Provider dropdown behavior + + -In Settings, the provider dropdown includes: +1. In Settings, choose provider: `OpenAI`. +2. Keep the default `API_BASE` (auto-filled). +3. Set `API_KEY` to your OpenAI key. +4. Choose model/voice. + + + + +1. In Settings, choose provider: `Deepinfra`. +2. Keep the default `API_BASE` (auto-filled). +3. Set `API_KEY` to your DeepInfra key. +4. Choose model/voice. + + + + +1. In Settings, choose provider: `Custom OpenAI-Like`. +2. Set `API_BASE` to your endpoint (example: `http://host.docker.internal:8880/v1`). +3. Set `API_KEY` if your provider requires one. +4. Choose model/voice. + + + + +## Provider Dropdown Behavior + +In Settings, provider options include: - `OpenAI` - `Deepinfra` -- `Custom OpenAI-Like` (for Kokoro, Orpheus, and other compatible endpoints) +- `Custom OpenAI-Like` (Kokoro, Orpheus, and other OpenAI-compatible endpoints) `API_BASE` guidance: -- For `OpenAI` and `Deepinfra`, OpenReader auto-fills the default endpoint. -- For `Custom OpenAI-Like`, set `API_BASE` to your server endpoint. -- In practice, you usually only set `API_BASE` when using a provider/endpoint that is not directly covered by the built-in dropdown defaults. +- `OpenAI` and `Deepinfra` auto-fill default endpoints. +- `Custom OpenAI-Like` requires setting `API_BASE` manually. -## Custom provider compatibility - -For custom providers, OpenReader expects these endpoints: +:::info OpenAI-Compatible API Shape +Custom providers should expose: - `GET /v1/audio/voices` - `POST /v1/audio/speech` +::: -If your provider exposes this interface, it can be used as an OpenAI-compatible TTS backend. +:::warning Server-Reachable API Base +TTS requests are sent from the Next.js server, not directly from the browser. `API_BASE` must be reachable from the server runtime. +::: -## Setup flow +## Related Guides -1. Select your provider in the OpenReader Settings modal. -2. If using `Custom OpenAI-Like` (or overriding a default), set `API_BASE`. -3. Set `API_KEY` if required by your provider. -4. Choose model and voice. - -For environment variables, see [Environment Variables](../reference/environment-variables). -For TTS quota behavior, see [TTS Rate Limiting](./tts-rate-limiting). -For auth behavior, see [Auth](./configuration). -For provider-specific integration guides, see [Kokoro-FastAPI](../integrations/kokoro-fastapi), [Orpheus-FastAPI](../integrations/orpheus-fastapi), [Deepinfra](../integrations/deepinfra), [OpenAI](../integrations/openai), and [Custom OpenAI](../integrations/custom-openai). +- [Environment Variables](../reference/environment-variables) +- [TTS Rate Limiting](./tts-rate-limiting) +- [Auth](./auth) +- [Kokoro-FastAPI](../integrations/kokoro-fastapi) +- [Orpheus-FastAPI](../integrations/orpheus-fastapi) +- [Deepinfra](../integrations/deepinfra) +- [OpenAI](../integrations/openai) +- [Custom OpenAI](../integrations/custom-openai) diff --git a/docs-site/docs/configure/tts-rate-limiting.md b/docs-site/docs/configure/tts-rate-limiting.md index 8bdf336..cdd892b 100644 --- a/docs-site/docs/configure/tts-rate-limiting.md +++ b/docs-site/docs/configure/tts-rate-limiting.md @@ -47,5 +47,5 @@ IP backstop daily limits: ## Related docs - Full variable list: [Environment Variables](../reference/environment-variables) -- Auth configuration: [Auth](./configuration) +- Auth configuration: [Auth](./auth) - Provider setup: [TTS Providers](./tts-providers) diff --git a/docs-site/docs/intro.md b/docs-site/docs/intro.md deleted file mode 100644 index 8a7b2e2..0000000 --- a/docs-site/docs/intro.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: intro -title: Introduction -slug: / ---- - -OpenReader WebUI 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**. - -It supports multiple TTS providers including OpenAI, DeepInfra, and custom OpenAI-compatible endpoints such as [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) and [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI). - -## Highlights - -- Multi-provider TTS support - - [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) (including multi-voice combinations) - - [Orpheus-FastAPI](https://github.com/Lex-au/Orpheus-FastAPI) - - Custom OpenAI-compatible endpoints (`/v1/audio/voices` and `/v1/audio/speech`) - - Cloud providers such as [DeepInfra](https://deepinfra.com/models/text-to-speech) and [OpenAI API](https://platform.openai.com/docs/pricing#transcription-and-speech) -- Server-side sync and storage - - External library import from a server-mounted folder - - Sync documents between browser and server for multi-device use -- Server-side audiobook export in `m4b`/`mp3`, with resumable chapter-based export -- Read-along highlighting for PDF and EPUB - - Optional word-by-word highlighting using server-side timestamps from [whisper.cpp](https://github.com/ggml-org/whisper.cpp) -- Sentence-aware narration that merges across pages/chapters for smoother playback -- Optimized Next.js TTS proxy with caching for faster repeat playback -- Customizable themes, TTS settings, and document handling - -## Start Here - -- [Docker Quick Start](./start-here/docker-quick-start) -- [Local Development](./start-here/local-development) -- [Environment Variables](./reference/environment-variables) -- [Auth](./configure/configuration) -- [Database and Migrations](./configure/database-and-migrations) -- [Object / Blob Storage](./configure/storage-and-blob-behavior) -- [TTS Providers](./configure/tts-providers) - -## Source Repository - -- GitHub: [richardr1126/OpenReader-WebUI](https://github.com/richardr1126/OpenReader-WebUI) diff --git a/docs-site/docs/introduction.md b/docs-site/docs/introduction.md new file mode 100644 index 0000000..c608431 --- /dev/null +++ b/docs-site/docs/introduction.md @@ -0,0 +1,48 @@ +--- +id: intro +title: Introduction +slug: / +--- + +OpenReader WebUI 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**. + +It supports multiple TTS providers including OpenAI, DeepInfra, and custom OpenAI-compatible endpoints such as [Kokoro-FastAPI](https://github.com/remsky/Kokoro-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`) + - [**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**: + - [**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` +- 🛜 **Server-side Document Storage** + - Documents are persisted in server blob/object storage for consistent access +- 📚 **External Library Import** + - Import documents from server-mounted folders +- 🎧 **Server-side Audiobook Export** in `m4b`/`mp3` with resumable chapter generation +- 📖 **Read Along Experience** + - Real-time highlighting for PDF/EPUB, with optional word-level [whisper.cpp](https://github.com/ggml-org/whisper.cpp) timestamps +- 🔐 **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** + - Theme, TTS, and document handling controls + +## 🚀 Start Here + +- [Docker Quick Start](./start-here/docker-quick-start) +- [Vercel Deployment](./start-here/vercel-deployment) +- [Local Development](./start-here/local-development) +- [Environment Variables](./reference/environment-variables) +- [Auth](./configure/auth) +- [Database and Migrations](./configure/database-and-migrations) +- [Object / Blob Storage](./configure/object-blob-storage) +- [Server Library Import](./configure/server-library-import) +- [TTS Providers](./configure/tts-providers) + +## Source Repository + +- GitHub: [richardr1126/OpenReader-WebUI](https://github.com/richardr1126/OpenReader-WebUI) diff --git a/docs-site/docs/project/support.md b/docs-site/docs/project/support-and-contributing.md similarity index 100% rename from docs-site/docs/project/support.md rename to docs-site/docs/project/support-and-contributing.md diff --git a/docs-site/docs/start-here/docker-quick-start.md b/docs-site/docs/start-here/docker-quick-start.md index 62bafa4..eec13a8 100644 --- a/docs-site/docs/start-here/docker-quick-start.md +++ b/docs-site/docs/start-here/docker-quick-start.md @@ -2,6 +2,9 @@ title: Docker Quick Start --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Prerequisites - A recent Docker version installed @@ -13,7 +16,10 @@ If you have suitable hardware, you can run Kokoro locally with Docker. See [Koko ## 1. Start the Docker container -Minimal setup (auth disabled, embedded storage ephemeral, no library import): + + + +Auth disabled, embedded storage ephemeral, no library import: ```bash docker run --name openreader-webui \ @@ -23,7 +29,10 @@ docker run --name openreader-webui \ ghcr.io/richardr1126/openreader-webui:latest ``` -Fully featured setup (persistent storage, embedded SeaweedFS `weed mini`, optional auth): + + + +Persistent storage, embedded SeaweedFS `weed mini`, optional auth, optional library mount: ```bash docker run --name openreader-webui \ @@ -39,21 +48,38 @@ docker run --name openreader-webui \ ghcr.io/richardr1126/openreader-webui:latest ``` -You can remove `/app/docstore/library` if you do not need server library import. -You can remove either `BASE_URL` or `AUTH_SECRET` to keep auth disabled. + + -Quick notes: +:::tip +Remove `/app/docstore/library` if you do not need server library import. +::: -- `API_BASE` should point to your TTS server base URL. -- Expose `8333` for direct browser access to embedded SeaweedFS presigned URLs. -- If `8333` is not exposed, uploads still work through `/api/documents/blob/upload/fallback`. -- To enable auth, set both `BASE_URL` and `AUTH_SECRET`. -- DB migrations run automatically during container startup via the shared entrypoint. +:::tip +Remove either `BASE_URL` or `AUTH_SECRET` to keep auth disabled. +::: -For all environment variables, see [Environment Variables](../reference/environment-variables). -For app/auth behavior, see [Auth](../configure/configuration). -For database startup and migration behavior, see [Database and Migrations](../configure/database-and-migrations). -For blob behavior and mounts, see [Object / Blob Storage](../configure/storage-and-blob-behavior). +:::tip TTS API Base +Set `API_BASE` to your reachable TTS server base URL. +::: + +:::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`. +::: + +:::info Auth and Migrations +- Auth is enabled only when both `BASE_URL` and `AUTH_SECRET` are set. +- DB/storage migrations run automatically at container startup via the shared entrypoint. +::: + +:::info Related Docs +- [Environment Variables](../reference/environment-variables) +- [Auth](../configure/auth) +- [Database and Migrations](../configure/database-and-migrations) +- [Object / Blob Storage](../configure/object-blob-storage) +::: ## 2. Configure settings in the app UI @@ -70,4 +96,8 @@ docker image rm ghcr.io/richardr1126/openreader-webui:latest || true && \ docker pull ghcr.io/richardr1126/openreader-webui:latest ``` +:::tip +If you use a mounted volume for `/app/docstore`, your persisted data remains after image updates. +::: + Visit [http://localhost:3003](http://localhost:3003) after startup. diff --git a/docs-site/docs/start-here/local-development.md b/docs-site/docs/start-here/local-development.md index 521a9b2..2a7e3bd 100644 --- a/docs-site/docs/start-here/local-development.md +++ b/docs-site/docs/start-here/local-development.md @@ -2,6 +2,9 @@ title: Local Development --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Prerequisites - Node.js (recommended with [nvm](https://github.com/nvm-sh/nvm)) @@ -14,10 +17,21 @@ npm install -g pnpm - A reachable TTS API server - [SeaweedFS](https://github.com/seaweedfs/seaweedfs) `weed` binary (required) + + + ```bash brew install seaweedfs ``` + + + +Install the `weed` binary from the [SeaweedFS releases](https://github.com/seaweedfs/seaweedfs/releases) and ensure it is available on `PATH`. + + + + Optional, depending on features: - [libreoffice](https://www.libreoffice.org) (required for DOCX conversion) @@ -39,7 +53,7 @@ cmake --build build -j --config Release echo WHISPER_CPP_BIN="$(pwd)/build/bin/whisper-cli" ``` -:::note +:::tip Set `WHISPER_CPP_BIN` in your `.env` to enable word-by-word highlighting. ::: @@ -66,10 +80,8 @@ cp .env.example .env Then edit `.env`. -Auth is enabled when both are set: - -- `BASE_URL` (for local dev, typically `http://localhost:3003`) -- `AUTH_SECRET` (generate with `openssl rand -base64 32`) +- No auth mode: leave `BASE_URL` or `AUTH_SECRET` unset. +- Auth enabled mode: set both `BASE_URL` (typically `http://localhost:3003`) and `AUTH_SECRET` (generate with `openssl rand -base64 32`). Optional: @@ -77,9 +89,12 @@ Optional: - Stable S3 credentials via `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` - External S3 storage by setting `USE_EMBEDDED_WEED_MINI=false` and related S3 vars +:::info For all environment variables, see [Environment Variables](../reference/environment-variables). -For app/auth behavior, see [Auth](../configure/configuration). -For storage configuration, see [Object / Blob Storage](../configure/storage-and-blob-behavior). +::: + +For app/auth behavior, see [Auth](../configure/auth). +For storage configuration, see [Object / Blob Storage](../configure/object-blob-storage). For database mode and migrations, see [Database and Migrations](../configure/database-and-migrations). 4. Run DB migrations. @@ -91,21 +106,32 @@ For database mode and migrations, see [Database and Migrations](../configure/dat pnpm migrate ``` -:::note +:::info If `POSTGRES_URL` is set, migrations target Postgres; otherwise local SQLite is used. To disable automatic startup migrations, set `RUN_DRIZZLE_MIGRATIONS=false` and/or `RUN_FS_MIGRATIONS=false`. You can run storage migration manually with `pnpm migrate-fs`. ::: 5. Start the app. + + + ```bash pnpm dev ``` -Or build + start production mode: + + ```bash pnpm build pnpm start ``` + + + +:::warning API Base Reachability +`API_BASE` must be reachable from the Next.js server process, not just your browser. +::: + Visit [http://localhost:3003](http://localhost:3003). diff --git a/docs-site/docs/start-here/vercel-deployment.md b/docs-site/docs/start-here/vercel-deployment.md index 50d06fe..a1dbcb4 100644 --- a/docs-site/docs/start-here/vercel-deployment.md +++ b/docs-site/docs/start-here/vercel-deployment.md @@ -2,17 +2,24 @@ title: Vercel Deployment --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + This guide covers deploying OpenReader WebUI 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`/`ffprobe-static`. -- `docx` conversion requires `soffice` (LibreOffice), which is not available in a standard Vercel runtime. -## 1. Required environment variables +:::warning DOCX Conversion Limitation +`docx` conversion requires `soffice` (LibreOffice), which is not available in a standard Vercel runtime. +::: -Set these in your Vercel project: +## 1. Environment Variables + + + ```bash POSTGRES_URL=postgres://... @@ -26,7 +33,8 @@ S3_FORCE_PATH_STYLE=true S3_PREFIX=openreader ``` -Optional but common: + + ```bash BASE_URL=https://your-app.vercel.app @@ -36,15 +44,26 @@ NEXT_PUBLIC_ENABLE_AUDIOBOOK_EXPORT=true NEXT_PUBLIC_ENABLE_WORD_HIGHLIGHT=true ``` + + + +:::tip For all variables and defaults, see [Environment Variables](../reference/environment-variables). +::: ## 2. FFmpeg/ffprobe packaging in Vercel functions `ffmpeg-static` and `ffprobe-static` binaries must be included in function traces. This repo already does that in `next.config.ts` via `outputFileTracingIncludes` for: -- `/api/audiobook(.*)` +- `/api/audiobook` +- `/api/audiobook/chapter` +- `/api/audiobook/status` - `/api/whisper` +:::info +`serverExternalPackages` should include `ffmpeg-static` and `ffprobe-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. ## 3. Function memory sizing @@ -66,7 +85,7 @@ Adjust memory per route if your files are larger or your plan differs. ## 4. Runtime expectations and caveats - Audiobook APIs require S3 configuration; otherwise they return `503`. -- `better-sqlite3` remains in `serverExternalPackages` for mixed/self-host setups, but production Vercel should use `POSTGRES_URL`. +- For production Vercel deploys, use `POSTGRES_URL` instead of SQLite. - Filesystem-to-object-store migrations run via server scripts/entrypoint (`scripts/migrate-fs-v2.mjs`), not API routes. - Vercel deployments do not run `scripts/openreader-entrypoint.mjs`, so run `pnpm migrate-fs` in a controlled environment when migrating legacy filesystem data. diff --git a/docs-site/docusaurus.config.ts b/docs-site/docusaurus.config.ts index 8cbef16..4abad5d 100644 --- a/docs-site/docusaurus.config.ts +++ b/docs-site/docusaurus.config.ts @@ -98,7 +98,7 @@ const config: Config = { { title: 'Community', items: [ - { label: 'Support', to: '/project/support' }, + { label: 'Support', to: '/project/support-and-contributing' }, { label: 'GitHub Discussions', href: 'https://github.com/richardr1126/OpenReader-WebUI/discussions' }, { label: 'Issues', href: 'https://github.com/richardr1126/OpenReader-WebUI/issues' }, ], diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts index 291cf19..b400937 100644 --- a/docs-site/sidebars.ts +++ b/docs-site/sidebars.ts @@ -21,14 +21,11 @@ const sidebars: SidebarsConfig = { label: 'Configure', items: [ 'configure/tts-providers', - { - type: 'doc', - id: 'configure/configuration', - label: 'Auth (Reccomended)', - }, + 'configure/auth', 'configure/tts-rate-limiting', 'configure/database-and-migrations', - 'configure/storage-and-blob-behavior', + 'configure/object-blob-storage', + 'configure/server-library-import', ], }, { @@ -45,7 +42,7 @@ const sidebars: SidebarsConfig = { { type: 'category', label: 'Project', - items: ['project/support', 'project/acknowledgements', 'project/license'], + items: ['project/support-and-contributing', 'project/acknowledgements', 'project/license'], }, ], };