Docker Compose

Use Docker Compose when you want a self-hosted Qodex stack on one machine. Compose is a good fit for internal staging, small deployments, on-premise trials, and teams that want Postgres included in the same stack. For production with managed AWS services, use the AWS Terraform reference.

What this stack includes

Qodex web app and agent container.
Postgres 17 for product state.
A persistent Qodex data volume for artifacts.
Optional Redis for queue mode.
Optional MinIO for S3-compatible artifact storage.

Prerequisites

Docker Engine 24+ with the Compose plugin.
At least 4 GB memory available to the Qodex container.
An OpenAI API key.
Random values for QODECLAW_SECRET_KEY and JWT_SECRET.

1. Create `docker-compose.yml`

services:
  qodex:
    image: ghcr.io/flinket/qodeclaw:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: "3000"
      DATABASE_URL: postgres://qodeclaw:qodeclaw@postgres:5432/qodeclaw
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      QODECLAW_SECRET_KEY: ${QODECLAW_SECRET_KEY}
      JWT_SECRET: ${JWT_SECRET}
      APP_URL: ${APP_URL:-http://localhost:3000}
      STORAGE_BACKEND: local
    volumes:
      - qodex-data:/data
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: qodeclaw
      POSTGRES_PASSWORD: qodeclaw
      POSTGRES_DB: qodeclaw
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U qodeclaw"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  pgdata:
  qodex-data:

The qodex-data volume stores artifacts such as screenshots, videos, DOM snapshots, logs, and attachments.

2. Add `.env`

Create a .env file next to the compose file.

OPENAI_API_KEY=sk-...
QODECLAW_SECRET_KEY=<32-or-more-char-random-string>
JWT_SECRET=<random-string>
APP_URL=http://localhost:3000

Keep this file out of version control.

3. Start the stack

docker compose up -d

Then watch Qodex boot:

docker compose logs -f qodex

The boot log shows which critical environment variables are present. It does not print secret values.

Add Redis when you need queue mode

Redis is optional. Without Redis, the scheduler and agent runner run in the Qodex container. With Redis, Qodex can run workers and scheduler processes separately. Add Redis when you need horizontal scaling or separate worker containers:

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

Then set:

REDIS_URL: redis://redis:6379

Add MinIO for S3-compatible storage

Use MinIO if you want the local stack to behave more like production S3.

  minio:
    image: minio/minio:latest
    restart: unless-stopped
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: minio
      MINIO_ROOT_PASSWORD: minio-secret-change-me
    volumes:
      - miniodata:/data

Then configure Qodex:

STORAGE_BACKEND: s3
S3_BUCKET: qodex-blobs
AWS_REGION: us-east-1
AWS_ACCESS_KEY_ID: minio
AWS_SECRET_ACCESS_KEY: minio-secret-change-me
AWS_ENDPOINT_URL: http://minio:9000

Create the bucket once from the MinIO console or client before running tests that write artifacts.

When Compose is enough

Compose is usually enough for:

A small internal self-hosted deployment.
A staging or proof-of-concept environment.
An on-premise install behind a corporate firewall.
A local environment that mirrors production behavior.

Use the AWS reference when you need managed Postgres backups, HTTPS termination, central logs, and a cleaner production scaling path.

Next steps

Environment variables

See the full configuration reference.

Storage backends

Choose local disk, S3, or MinIO.

Secret management

Understand QODECLAW_SECRET_KEY before production.

AWS Terraform reference

Move from one host to managed AWS infrastructure.

Get started

Concepts

PR review

API testing

UI testing

Security testing

Run tests

Findings

Memory

Skills

Integrations

Self-hosted

Account

Docker Compose

Docker Compose

What this stack includes

Prerequisites

1. Create `docker-compose.yml`

2. Add `.env`

3. Start the stack

Add Redis when you need queue mode

Add MinIO for S3-compatible storage

When Compose is enough

Next steps

Environment variables

Storage backends

Secret management

AWS Terraform reference

​Docker Compose

​What this stack includes

​Prerequisites

​1. Create docker-compose.yml

​2. Add .env

​3. Start the stack

​Add Redis when you need queue mode

​Add MinIO for S3-compatible storage

​When Compose is enough

​Next steps

Environment variables

Storage backends

Secret management

AWS Terraform reference

Docker Compose

What this stack includes

Prerequisites

1. Create `docker-compose.yml`

2. Add `.env`

3. Start the stack

Add Redis when you need queue mode

Add MinIO for S3-compatible storage

When Compose is enough

Next steps