Kubernetes / Railway

Production deployment on Kubernetes using Railway or your own cluster.

Railway (recommended)

Railway is the recommended production host for Cognisafe. Each service is deployed as an independent Railway service from this monorepo, giving you per-service scaling, logs, and metrics.

One-time setup

1. Create a Railway project

   Go to railway.app and create a new project.

2. Add managed services

   In your Railway project, add:

   • PostgreSQL — use the TimescaleDB plugin
   • Redis — standard Redis service

   Copy the connection strings Railway provides — you’ll need them for the service env vars below.

3. Create the four application services

   Create one Railway service per component. Use the settings from the table below:

   Service	Root directory	Dockerfile	Notes
   api	api/	Dockerfile	Pre-deploy: alembic upgrade head
   proxy	proxy/	Dockerfile	—
   web	web/	Dockerfile	—
   safety_worker	api/	Dockerfile.worker	Start: python workers/safety_scorer.py

4. Set environment variables

   Configure the env vars for each service as shown in the sections below.

5. Connect your GitHub repo

   In Railway: Settings → Source → connect your GitHub repository. Set the target branch (main or platform). Railway redeploys all services on every push to that branch.

The api service must run alembic upgrade head before it starts serving traffic. This is configured as a pre-deploy command in api/railway.toml. Do not remove or skip it — the API will crash on startup if migrations have not been applied.

Environment variables per service

api

POSTGRES_URL=postgresql+asyncpg://<railway-postgres-url>
REDIS_URL=redis://<railway-redis-url>
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_PRO=price_...
STRIPE_PRICE_TEAM=price_...
INTERNAL_API_SECRET=<long-random-secret>

proxy

UPSTREAM_URL=https://api.openai.com
API_BACKEND_URL=https://<your-api-railway-domain>
PROXY_API_KEY=<same as a cognisafe API key>

web

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...
INTERNAL_API_SECRET=<same value as api service>
API_URL=https://<your-api-railway-domain>
NEXT_PUBLIC_API_URL=https://<your-api-railway-domain>

safety_worker

POSTGRES_URL=<same as api>
REDIS_URL=<same as api>
OPENAI_API_KEY=sk-...
SCORER_MODEL=gpt-4o-mini

Custom domains

In Railway: Settings → Networking → Generate Domain (or add your own CNAME).

Recommended mapping:

Domain	Railway service
cognisafe.uk	web
api.cognisafe.uk	api
proxy.cognisafe.uk	proxy

Scaling

Scale the safety_worker service by increasing its replica count in Railway’s service settings. The workers are stateless — each reads independently from the Redis queue.

---

Bare Kubernetes (Helm)

A Helm chart is available for teams running their own Kubernetes cluster.

helm repo add cognisafe https://charts.cognisafe.uk
helm repo update

helm install cognisafe cognisafe/cognisafe \
  --namespace cognisafe \
  --create-namespace \
  --set api.postgresUrl="postgresql+asyncpg://..." \
  --set api.redisUrl="redis://..." \
  --set proxy.upstreamUrl="https://api.openai.com" \
  --set api.stripeSecretKey="sk_live_..." \
  --set safetyWorker.openaiApiKey="sk-..."

The chart deploys all four application services as separate Deployment resources, plus Service and Ingress objects. PostgreSQL and Redis are expected to be provided externally (managed cloud databases or separate Helm releases).

Values reference

Value	Description	Default
api.postgresUrl	asyncpg connection string	—
api.redisUrl	Redis connection string	—
api.replicaCount	API pod replicas	2
proxy.upstreamUrl	LLM provider upstream URL	https://api.openai.com
proxy.replicaCount	Proxy pod replicas	2
safetyWorker.replicaCount	Worker pod replicas	3
safetyWorker.openaiApiKey	OpenAI key for PyRIT scorers	—
safetyWorker.scorerModel	PyRIT scoring model	gpt-4o-mini
web.clerkPublishableKey	Clerk publishable key	—
web.clerkSecretKey	Clerk secret key	—

Running migrations on Kubernetes

The Helm chart includes a pre-upgrade Job that runs alembic upgrade head:

helm upgrade cognisafe cognisafe/cognisafe ...
# The migration job runs automatically before the API Deployment rolls out

To run migrations manually:

kubectl run alembic-migrate \
  --image=ghcr.io/cognisafe/api:latest \
  --env="POSTGRES_URL=postgresql+asyncpg://..." \
  --restart=Never \
  -- alembic upgrade head