Docker Compose

Run the full Cognisafe stack locally or on a VM.

Docker Compose is the fastest way to get the full stack running. All six services start with a single command.

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• Git

Steps

1. Clone the repository

   git clone https://github.com/cognisafe/cognisafe.git
   cd cognisafe
   
2. Configure environment variables

   cp .env.example .env
   

   Open .env and fill in the required values:

   # Required
   PROXY_API_KEY=csk_your_key_here          # auth key for the proxy
   OPENAI_API_KEY=sk-...                    # used by PyRIT safety scorers
   STRIPE_SECRET_KEY=sk_live_...            # Stripe API key
   STRIPE_WEBHOOK_SECRET=whsec_...          # Stripe webhook signing secret
   STRIPE_PRICE_PRO=price_...               # Stripe price ID for Pro tier
   STRIPE_PRICE_TEAM=price_...              # Stripe price ID for Team tier
   
   # Pre-filled with sensible defaults — change if needed
   POSTGRES_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/cognisafe
   REDIS_URL=redis://redis:6379
   

   For local development without Stripe, leave the Stripe vars blank — billing routes will return errors but all other functionality works.

3. Start the stack

   docker compose -f infra/docker-compose.yml up
   

   On first run, Docker pulls the images and the migrate service runs alembic upgrade head to initialise the database schema before the API starts.

   The migrate service is a one-shot container. It runs database migrations and exits with code 0. If you see it listed as “exited” in docker compose ps, that is expected — it completed successfully.

4. Open the dashboard

   Navigate to http://localhost:3000.

   The proxy is available at http://localhost:8080 and the API at http://localhost:8000.

5. Point your SDK at the local stack

   import cognisafe
   
   cognisafe.configure(
       api_key="csk_your_key_here",  # same as PROXY_API_KEY in .env
       project_id="my-app",
       proxy_url="http://localhost:8080",
       api_url="http://localhost:8000",
   )
   cognisafe.patch_openai()
   

Services

Service	Port	Role
postgres	5432	TimescaleDB — primary datastore
redis	6379	Job queue (safety_score_jobs)
migrate	—	One-shot: runs alembic upgrade head and exits
api	8000	FastAPI backend — REST API and Stripe webhooks
safety_worker	—	PyRIT scoring worker
proxy	8080	Go LLM reverse proxy
web	3000	Next.js dashboard

Scaling safety workers

The safety_worker is stateless and horizontally scalable. Increase throughput by running multiple instances:

docker compose -f infra/docker-compose.yml up --scale safety_worker=3

Each worker independently reads from the Redis queue. Three workers process three scoring jobs concurrently.

Updating

git pull
docker compose -f infra/docker-compose.yml up --build

Database migrations run automatically via the migrate service on startup.

Stripe local webhook forwarding

To test billing flows locally, forward Stripe webhooks to your local API:

stripe listen --forward-to localhost:8000/webhook/stripe

Copy the webhook signing secret printed by the CLI into STRIPE_WEBHOOK_SECRET in .env, then restart the API service.

Running in detached mode

docker compose -f infra/docker-compose.yml up -d
docker compose -f infra/docker-compose.yml logs -f api safety_worker