Skip to main content

Deployment and Operations

The production start command runs two local servers: FastAPI serves the API and the built React SPA, while a separate static server serves the built documentation site.

Build and Start​

Root scripts:

npm run install:all
npm run build
npm start

npm run build builds the web app, builds the docs site, and syncs the backend environment.

Server Startup​

npm start runs scripts/start-production.sh, which starts:

npm --prefix docs-site run serve -- --host "$DOCS_HOST" --port "$DOCS_PORT"
uv run python -m app.run

The API entrypoint:

  1. Ensures the target database exists.
  2. Runs alembic upgrade head.
  3. Starts uvicorn.

The docs server defaults to http://localhost:3050. Override it with DOCS_PORT and DOCS_HOST.

Required Environment​

Minimum production values:

  • DATABASE_URL
  • JWT_SECRET

Common optional values:

  • WEB_ORIGIN
  • CORS_ORIGIN
  • ADMIN_EMAILS
  • RESEND_API_KEY
  • DISCORD_CLIENT_ID
  • DISCORD_CLIENT_SECRET
  • VOYAGE_API_KEY
  • ANTHROPIC_API_KEY
  • LANGFUSE_*
  • LANGSMITH_*
  • DOCS_PORT
  • DOCS_HOST

See README.md and server/.env.example for the full list.

Storage​

Plan persistent storage for:

  • Private core-rule files under server/storage/.
  • Public media/uploads under the configured uploads root.
  • PostgreSQL data, including pgvector embeddings.

Do not rely on ephemeral filesystem storage for uploaded user content.

Health and Static Serving​

The API exposes health checks and serves:

  • /api/* for backend routes.
  • /uploads/* for public media.
  • SPA fallback for frontend routes when web/dist exists.

Domain 404s from API handlers are preserved and not replaced with the SPA shell.

Operational Checks​

  • Confirm migrations apply on deploy.
  • Confirm web/dist exists after build.
  • Confirm docs-site/build exists after build.
  • Confirm DOCS_PORT is available where the docs server should run.
  • Confirm upload/private storage paths are mounted persistently.
  • Confirm AI provider keys are present only where AI features should work.
  • Confirm Langfuse/LangSmith tracing keys are either valid or absent.