Skip to content

docker-compose.mdx

Latest commit

 

History

History
143 lines (97 loc) · 4.27 KB

docker-compose.mdx

File metadata and controls

143 lines (97 loc) · 4.27 KB
Raw
title Docker Compose
description Run Codex Pooler with Docker Compose for a small self-hosted install.

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
  • Git, if you are cloning the repository
  • openssl
  • A checked-out Codex Pooler repository
git clone https://github.com/icoretech/codex-pooler.git
cd codex-pooler

Generate the local environment

For a reproducible install, choose the release image before creating .env. The generator defaults to latest, which is convenient for a quick trial but less explicit for a real install.

{/* x-release-please-start-version */}

export CODEX_POOLER_IMAGE=ghcr.io/icoretech/codex-pooler
export CODEX_POOLER_IMAGE_TAG=0.3.0
scripts/self-host/generate-env.sh

{/* x-release-please-end */}

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.

If you already generated .env, edit CODEX_POOLER_IMAGE_TAG before docker compose pull when you want a specific release instead of the floating latest tag. If port 4000 is already in use, set CODEX_POOLER_HTTP_PORT before generation or edit it in .env before starting the stack.

Start Codex Pooler

Pull and start the stack:

docker compose pull
docker compose up -d

The first run pulls the app and Postgres images, waits for Postgres health, runs the migration container, then starts the web app.

Open the local site:

http://localhost:4000

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

To verify the first-run redirect from the shell:

curl -sS -D - -o /dev/null http://localhost:4000/ | grep -i '^location: /bootstrap'
curl -fsS http://localhost:4000/bootstrap/status

The status endpoint should return {"status":"ok","bootstrap":"pending"} on a fresh database. Use http://localhost:4000 for the default Compose stack even if the Phoenix startup banner prints an endpoint URL such as https://localhost; the Compose port mapping is the local URL to open. A release image includes the OS timezone database used for operator timezone display.

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://codex-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.