Deployment notes

CXGear is not a single website process. A working deployment is a small set of services that share a database and a few public URLs. This page is for admins and implementers who stand up or troubleshoot an environment.

For local development details, see Environments.

Services

Service	Role
Web	Browser UI (projects, Records, Billing, Dialler, …)
API	Login, projects, billing, channels, job creation, public ingest/trigger
Runtime	Actually runs spinner jobs (steps, AI, channels)
Database	Postgres — orgs, tables, jobs, sessions, billing state
Docs (optional)	This documentation site

If web and API are up but runtime is not, people can click Run now and create jobs, but jobs will not progress. That is the most common “everything looks fine but nothing happens” failure.

Screenshot needed

Architecture sketch or ops checklist showing web, API, runtime, and database.

Where: Internal runbook / deployment diagram

Save as: src/assets/screenshots/41-deployment-services.png

Public URLs (production sketch)

Host	Purpose
app.cxgear.ai	Web UI
api.cxgear.ai	API (`/api/v1/…`) and OpenAPI (`/docs`)
docs.cxgear.ai	Product documentation (this site)

Runtime workers usually do not need a public hostname; they need database access and outbound network to providers (LLM, Meta, SMS, and so on).

PUBLIC_API_URL

PUBLIC_API_URL is the publicly reachable base URL of the API — for example https://api.cxgear.ai.

CXGear uses it to build:

OAuth redirect URIs (WhatsApp / Meta)
Webhook URLs shown in the product
Links and callbacks that external systems must call

Rule	Why
Must be HTTPS in production	Providers reject insecure callbacks
Must match provider app settings exactly	OAuth redirect mismatch is fatal
Must be reachable from the public internet	Meta and CRMs cannot call `localhost`
Should not point at the web host	Callbacks are API routes, not UI routes

Example WhatsApp callback:

https://api.cxgear.ai/api/v1/channels/whatsapp/oauth/callback

If you change API hostnames, update PUBLIC_API_URL and every provider console entry that embeds the old URL.

Other important variables

Variable	Purpose
`PUBLIC_APP_URL`	Public base URL of the web app
`DATABASE_URL`	Postgres connection for API and runtime
`META_APP_ID` / `META_APP_SECRET`	WhatsApp Meta OAuth
Payment provider keys	Stripe / Razorpay for Billing checkout

Never commit secrets to git. Inject them through your host’s secret store.

Documentation site (docs.cxgear.ai)

The docs app lives under apps/docs and is intended to publish to https://docs.cxgear.ai.

Local preview:

npm run dev:docs

Open http://localhost:4321.

Docs are static guidance for operators and integrators. They do not replace OpenAPI for request schemas — use https://api.cxgear.ai/docs for live API reference.

Health checklist

Before declaring an environment ready:

Web loads and can reach the API
Sign up / login works and sessions persist
Runtime is running and a test spinner job completes
PUBLIC_API_URL matches real HTTPS DNS
Billing page loads (even on Trial)
Docs are linked for your team (docs.cxgear.ai or internal mirror)

Success looks like

Users work on the app host; integrations call the API host
OAuth and ingest webhooks succeed without redirect errors
Jobs progress only when runtime is healthy
Docs are available at docs.cxgear.ai for training

Common problems

Problem	Likely cause	What to do
Jobs stuck queued/running forever	Runtime not deployed	Start runtime workers
OAuth redirect mismatch	`PUBLIC_API_URL` wrong	Align env and Meta app settings
CRM cannot ingest	API not public or wrong path	Expose API; copy URL from product
UI works, API 401 storms	Clock skew or bad JWT secret	Check API auth config
Docs 404 for sidebar pages	Docs not rebuilt after content add	Redeploy docs app