From 8310091816e3c597ea1c4bd50a1eaa303c93c9d6 Mon Sep 17 00:00:00 2001 From: Richard R Date: Wed, 20 May 2026 14:17:07 -0600 Subject: [PATCH] docs(deploy): update compute worker and Vercel deployment guides for Synadia + Railway Add a comprehensive Synadia Cloud and Railway setup guide to the compute worker deployment docs, including step-by-step environment variable configuration and example image tags. Update Vercel deployment instructions with a quick start for external compute worker integration via Railway and Synadia NGS. Document new `.env.prod` pattern in .gitignore for production environment management. --- .gitignore | 1 + docs-site/docs/deploy/compute-worker.md | 84 ++++++++++++++++++---- docs-site/docs/deploy/vercel-deployment.md | 14 +++- 3 files changed, 83 insertions(+), 16 deletions(-) diff --git a/.gitignore b/.gitignore index c006683..4014f63 100644 --- a/.gitignore +++ b/.gitignore @@ -33,6 +33,7 @@ yarn-error.log* # env files (can opt-in for committing if needed) .env +.env.prod .dockerignore *.creds diff --git a/docs-site/docs/deploy/compute-worker.md b/docs-site/docs/deploy/compute-worker.md index 16c3d8d..8e2da44 100644 --- a/docs-site/docs/deploy/compute-worker.md +++ b/docs-site/docs/deploy/compute-worker.md @@ -16,6 +16,7 @@ The app server enqueues jobs and polls status. Queue durability and retries are - App server image: `ghcr.io/richardr1126/openreader` - Compute worker image: `ghcr.io/richardr1126/openreader-compute-worker` +- Compute worker image (example pinned tag): `ghcr.io/richardr1126/openreader-compute-worker:refactor-ppdoclayoutv3-onnx-layout-parsing` ## Worker environment variables @@ -68,20 +69,73 @@ COMPUTE_WORKER_TOKEN= - `GET /health/live` - `GET /health/ready` -## Authenticating with Synadia Cloud (NGS) +## Synadia Cloud + Railway Setup (Complete Guide) -If you are using a free Synadia Cloud account to back your compute queue in production: +Use this end-to-end guide when your queue backend is Synadia Cloud (NGS) and your worker runs on Railway. -1. **Obtain your credentials file**: When creating a user or a service account on Synadia Cloud, download your credentials file (usually named `.creds`). -2. **Configure NATS URL**: Synadia Cloud's server address is `tls://connect.ngs.global:4222`. Set this as your `NATS_URL`. -3. **Configure Authentication**: - - **Using a local file path**: Set `NATS_CREDS_FILE` to the path of your `.creds` file: - ```env - NATS_URL=tls://connect.ngs.global:4222 - NATS_CREDS_FILE=/app/secrets/NGS-Default-compute-worker.creds - ``` - - **Using raw content (Recommended for Railway, Fly.io, etc.)**: Set `NATS_CREDS` to the exact content of your `.creds` file (including the begin/end banners for JWT and NKEY seed). Since `.creds` contains newlines, wrap the entire value in quotes or paste it directly into your cloud provider's Secrets/Environment settings: - ```env - NATS_URL=tls://connect.ngs.global:4222 - NATS_CREDS="-----BEGIN NATS USER JWT-----\neyJ0...------END USER NKEY SEED------" - ``` +### 1. Create Synadia account and credentials + +1. Create a Synadia Cloud account and create/select your NGS environment. +2. Create a user or service account for OpenReader compute worker access. +3. Download the generated credentials file (usually `.creds`) and keep it secure. + +You will use: + +- `NATS_URL=tls://connect.ngs.global:4222` +- The full `.creds` file content + +### 2. Deploy compute worker on Railway + +Create a Railway service from: + +```text +ghcr.io/richardr1126/openreader-compute-worker:refactor-ppdoclayoutv3-onnx-layout-parsing +``` + +Set the container port to `8081`, then enable public networking to get a worker URL. + +### 3. Configure Railway worker environment variables + +Set these in the Railway worker service: + +```env +COMPUTE_WORKER_HOST=0.0.0.0 +COMPUTE_WORKER_PORT=8081 +COMPUTE_WORKER_TOKEN= + +NATS_URL=tls://connect.ngs.global:4222 +NATS_CREDS="-----BEGIN NATS USER JWT----- +... +------END USER NKEY SEED------" + +S3_BUCKET= +S3_REGION= +S3_ACCESS_KEY_ID= +S3_SECRET_ACCESS_KEY= +S3_ENDPOINT= +S3_FORCE_PATH_STYLE=true +S3_PREFIX=openreader +``` + +Notes: + +- `NATS_CREDS` should be the full Synadia `.creds` file content, including begin/end markers. +- Keep `COMPUTE_WORKER_TOKEN` identical between app server and worker. +- If your platform supports mounted files, you can use `NATS_CREDS_FILE` instead of `NATS_CREDS`. + +### 4. Configure the OpenReader app server (worker mode) + +Set these env vars on the app server: + +```env +COMPUTE_MODE=worker +COMPUTE_WORKER_URL=https:// +COMPUTE_WORKER_TOKEN= +``` + +### 5. Verify health + +After deploy, check: + +- `GET https:///health/live` +- `GET https:///health/ready` diff --git a/docs-site/docs/deploy/vercel-deployment.md b/docs-site/docs/deploy/vercel-deployment.md index 7fa3842..b587d1b 100644 --- a/docs-site/docs/deploy/vercel-deployment.md +++ b/docs-site/docs/deploy/vercel-deployment.md @@ -41,7 +41,7 @@ ADMIN_EMAILS=you@example.com # comma-separated; admins manage TTS + features in # local = requires native binaries/models in-process (not recommended on Vercel) # worker = external durable compute worker (recommended) COMPUTE_MODE=worker -COMPUTE_WORKER_URL=https://your-compute-worker.example.com +COMPUTE_WORKER_URL=https:// COMPUTE_WORKER_TOKEN=... # First-boot seed for the TTS shared provider (optional; manage in-app afterwards) @@ -53,6 +53,18 @@ COMPUTE_WORKER_TOKEN=... `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). ::: +## 1a. Railway + Synadia quick start (worker mode) + +If your Vercel app uses an external compute worker on Railway with Synadia Cloud (NGS): + +1. Deploy a Railway service from: + - `ghcr.io/richardr1126/openreader-compute-worker:refactor-ppdoclayoutv3-onnx-layout-parsing` +2. Enable public networking on that Railway service and set: + - `COMPUTE_WORKER_URL=https://` (in Vercel) +3. Use the same `COMPUTE_WORKER_TOKEN` value in both Vercel and Railway worker env vars. + +For complete Railway worker env vars (`NATS_*`, `S3_*`, health checks, and Synadia `.creds` guidance), see [Compute Worker (NATS JetStream)](./compute-worker). + ## 2. First-run admin configuration (recommended) After the first successful deploy and admin login, open **Settings → Admin** and configure: