Operations

Deployment

Run Orbit locally with Docker Compose, then promote the same topology to production.

Runtime stack

Orbit APICore API service (src/orbit_api/)

PostgreSQLDefault runtime database

PrometheusScrapes /v1/metrics

OpenTelemetryOTLP collector for traces

Local deployment

terminal

docker compose up --build

Migrations

Alembic migrations live in migrations/. Run on deploy or enable startup auto-migrate.

terminal

python -m alembic upgrade head

Optional startup migration flag:

.env

ORBIT_AUTO_MIGRATE=true

Required environment variables

MDE_DATABASE_URLPostgreSQL DSN

ORBIT_JWT_SECRETJWT signing secret

ORBIT_JWT_ISSUERExpected JWT issuer

ORBIT_JWT_AUDIENCEExpected JWT audience

Vercel frontend setup

Host the Orbit frontend on Vercel and point it at your Orbit API runtime.

Browser clients never receive Orbit API bearer credentials. Next.js proxy routes exchange dashboard sessions for short-lived tenant-scoped JWTs.

front-end/.env.local

NEXT_PUBLIC_ORBIT_API_BASE_URL=https://orbit-api-ic4qh4dzga-uc.a.run.app
# Optional if different from NEXT_PUBLIC_ORBIT_API_BASE_URL:
# ORBIT_DASHBOARD_PROXY_BASE_URL=https://orbit-api-ic4qh4dzga-uc.a.run.app
ORBIT_DASHBOARD_PROXY_AUTH_MODE=exchange
ORBIT_DASHBOARD_ORBIT_JWT_SECRET=<same-secret-as-orbit-api-jwt-verifier>
# Optional exchange controls:
# ORBIT_DASHBOARD_ORBIT_JWT_ISSUER=orbit
# ORBIT_DASHBOARD_ORBIT_JWT_AUDIENCE=orbit-api
# ORBIT_DASHBOARD_ORBIT_JWT_TTL_SECONDS=300
ORBIT_DASHBOARD_AUTH_MODE=oidc
ORBIT_DASHBOARD_OIDC_GOOGLE_CLIENT_ID=<google-client-id>
ORBIT_DASHBOARD_OIDC_GOOGLE_CLIENT_SECRET=<google-client-secret>
ORBIT_DASHBOARD_OIDC_GITHUB_CLIENT_ID=<github-client-id>
ORBIT_DASHBOARD_OIDC_GITHUB_CLIENT_SECRET=<github-client-secret>
ORBIT_DASHBOARD_SESSION_SECRET=<long-random-secret>
# Optional:
# ORBIT_DASHBOARD_SESSION_TTL_SECONDS=43200
# ORBIT_DASHBOARD_ALLOWED_ORIGINS=https://orbit-memory.vercel.app
# ORBIT_DASHBOARD_ALLOW_MISSING_ORIGIN=false
# ORBIT_DASHBOARD_OIDC_ALLOW_UNSIGNED_ID_TOKEN_FALLBACK=false

If frontend and API are on different domains, allow your Vercel origin in backend CORS:

orbit-api.env

ORBIT_CORS_ALLOW_ORIGINS=https://orbit-memory.vercel.app

Plan quota controls (Free + invite-only Pilot Pro):

orbit-api.env

ORBIT_RATE_LIMIT_EVENTS_PER_MONTH=10000
ORBIT_RATE_LIMIT_QUERIES_PER_MONTH=50000
ORBIT_RATE_LIMIT_FREE_API_KEYS=3
ORBIT_RATE_LIMIT_PILOT_PRO_EVENTS_PER_MONTH=250000
ORBIT_RATE_LIMIT_PILOT_PRO_QUERIES_PER_MONTH=1000000
ORBIT_RATE_LIMIT_PILOT_PRO_API_KEYS=25
ORBIT_PILOT_PRO_ACCOUNT_KEYS=acct_team_a,acct_team_b
ORBIT_PILOT_PRO_RESEND_API_KEY=<resend-api-key>
ORBIT_PILOT_PRO_REQUEST_ADMIN_EMAIL=hello@theorbit.dev
ORBIT_PILOT_PRO_REQUEST_FROM_EMAIL="Orbit <onboarding@resend.dev>"
ORBIT_PILOT_PRO_EMAIL_TIMEOUT_SECONDS=10
ORBIT_USAGE_WARNING_THRESHOLD_PERCENT=80
ORBIT_USAGE_CRITICAL_THRESHOLD_PERCENT=95

Production checklist

JWT issuer/audience/secret configured with non-default secrets.

PostgreSQL backups and retention policy enabled.

Prometheus scraping and alerting configured.

OTel exporter endpoint connected to your tracing backend.

SLO alerts on latency, 401, 429, and 5xx rates.

Migration command integrated in CI/CD release flow.

Integration tests cover ingest -> retrieve -> feedback loop.

Vercel frontend env vars are configured and CORS allows your Vercel origin.

Configuration ->