Deploy & domain
How the public docs app is deployed, which runtime variables it needs, and how to attach a customer-facing custom domain.
Deployment unit
The docs site is the @tyxter/docs Next.js app inapps/docs. It can run as a standalone container through the included Dockerfile or as a platform-managed Next deployment. The app is static by default except for the status page, which reads the public API status endpoint at runtime.
Required environment
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_API_BASE_URL | Browser-visible API base URL shown in examples. |
API_BASE_URL | Server-side API base URL for OpenAPI server generation, examples, and status fallback. |
STATUS_API_BASE_URL | Optional server-side override for the status page. Use this when the docs deployment reaches the API through an internal service URL. |
PORT | Optional platform-managed port for container start. Local scripts default to 3002; use next dev -p PORT for an explicit override. |
Custom domain wiring
- Provision the docs app behind the canonical docs host for the deployment.
- Point DNS at the deployment target with a CNAME for managed platforms or an A/AAAA record for your ingress load balancer.
- Terminate TLS at the platform or ingress layer and enforce HTTPS redirects before traffic reaches Next.js.
- Set
NEXT_PUBLIC_API_BASE_URLto the public API origin that customers should copy from examples. - Run
pnpm --filter @tyxter/docs buildand smoke-check/,/quickstart,/api-reference, and/status.
Keep docs and API on separate hosts. The dashboard session cookie is a product surface owned by the dashboard; public docs should not share that cookie scope.
Local verification
pnpm --filter @tyxter/docs typecheck
pnpm --filter @tyxter/docs build
pnpm --filter @tyxter/docs dev