Docker Compose

Docker Compose is the quickest self-host path for a laptop, lab server, or small single-node install. It runs the Codex Pooler release image with a local Postgres database and writes the release secrets into a private .env file.

Use it when you want a simple first install before moving to Kubernetes.

Prerequisites

You need:

• Docker with Compose
• openssl
• A checked-out Codex Pooler repository

git clone https://github.com/icoretech/codex-pooler.git
cd codex-pooler

Generate the local environment

Create the local .env file before starting the stack:

scripts/self-host/generate-env.sh

The generated .env contains release secrets, encryption roots, database settings, and image settings such as CODEX_POOLER_IMAGE and CODEX_POOLER_IMAGE_TAG. Keep it private. Don’t commit it, paste it into tickets, or reuse values between public installs.

For real installs, run an explicit release image tag instead of a floating tag. The tag should identify the exact image you meant to deploy.

CODEX_POOLER_IMAGE=ghcr.io/icoretech/codex-pooler
CODEX_POOLER_IMAGE_TAG=v0.1.0

Start Codex Pooler

Pull and start the stack:

docker compose pull
docker compose up -d

Open the local site:

http://localhost:4000

On the first visit, create the owner account at /bootstrap. After sign-in, start with /admin/pools.

Bootstrap runtime access

After the owner account exists:

1. Create a Pool in /admin/pools
2. Import or connect upstream accounts in /admin/upstreams
3. Create a Pool API key in /admin/api-keys
4. Point clients at one of the runtime base URLs

Codex backend compatibility route:
http://localhost:4000/backend-api/codex

OpenAI-compatible /v1 surface:
http://localhost:4000/v1

Operator MCP endpoint:
http://localhost:4000/mcp

Use a Pool API key for /backend-api and /v1. Use an operator MCP token for /mcp.

For a deployed host, replace http://localhost:4000 with https://pooler.example.com.

Health and readiness

Check that the web process responds before handing traffic to clients:

curl -fsS http://localhost:4000/healthz
curl -fsS http://localhost:4000/readyz

/healthz confirms the endpoint is alive. /readyz is the safer check for accepting runtime traffic.

You can inspect the Compose stack with:

docker compose ps
docker compose logs -f app

Stop or reset

Stop the stack while keeping the database volume:

docker compose down

Stop the stack and remove the local database volume:

docker compose down -v

Only use down -v when you intentionally want to remove local Codex Pooler data.

Compose limits

Docker Compose is a simple self-host flow, not a high-availability topology. It is best for a single web process and local Postgres.

Backend websocket sessions keep live upstream websocket state inside the web app process. Don’t scale Compose web replicas unless you also design clustering and owner-forwarding for that environment. If you need multiple web replicas, use the Helm chart and keep the replica caveat in that deployment plan.