Skip to main content

Documentation Index

Fetch the complete documentation index at: https://cognisafeltd.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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:
ServiceRoot directoryDockerfileNotes
apiapi/DockerfilePre-deploy: alembic upgrade head
proxyproxy/Dockerfile—
webweb/Dockerfile—
safety_workerapi/Dockerfile.workerStart: 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:
DomainRailway service
cognisafe.ukweb
api.cognisafe.ukapi
proxy.cognisafe.ukproxy

​
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

ValueDescriptionDefault
api.postgresUrlasyncpg connection string—
api.redisUrlRedis connection string—
api.replicaCountAPI pod replicas2
proxy.upstreamUrlLLM provider upstream URLhttps://api.openai.com
proxy.replicaCountProxy pod replicas2
safetyWorker.replicaCountWorker pod replicas3
safetyWorker.openaiApiKeyOpenAI key for PyRIT scorers—
safetyWorker.scorerModelPyRIT scoring modelgpt-4o-mini
web.clerkPublishableKeyClerk publishable key—
web.clerkSecretKeyClerk 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