ibexharness
DocsBlogReleasesRoadmap
GitHub
ibexharness

Documentation

Docker Compose (dev)Kubernetes (production)Environment variables
Deployment›Docker Compose (dev)
Deployment

Docker Compose (dev)

Run the local dependency stack with Make targets, migrate Postgres, seed dev fixtures, and start auth and proxy on the host.

Phase 1 local development runs data stores in Docker and Go services on the host for fast iteration. The compose file under infra/compose/dev/ ships Postgres (pgvector), Redis Stack, ClickHouse, and MinIO — no application containers.

Prerequisites

Docker Compose v2, GNU Make, Git Bash on Windows, and ports 5432, 6379, 8123, 9000–9002 available. See the Quickstart for the five-minute path.

Compose services and ports

ServiceImageHost portPurpose
Postgres + pgvectorpgvector/pgvector:pg165432Primary OLTP + migrations
Redis Stackredis/redis-stack:7.4.0-v16379Rate limits, readiness probes
ClickHouseclickhouse/clickhouse-server:24.88123 (HTTP), 9002 (native)Analytics (Phase 2+)
MinIOminio/minio9000 (API), 9001 (console)Object storage (Phase 2+)

ClickHouse native is mapped to 9002 so it does not collide with MinIO on 9000.

Application services (run separately on the host):

ServiceHTTPgRPCNotes
Proxy8080—/health, /ready, /metrics, /v1/*
Auth80819091gRPC ValidateToken / ValidateAgent

Boot sequence

1

Start dependencies

From the repo root: make compose-dev-up. Waits for healthy Postgres and Redis.

2

Apply migrations

make db-migrate is idempotent. Use make db-version to inspect the current revision.

3

Seed dev fixtures

make db-seed inserts a fixed org, agent, and PAT. Never run against staging or production.

4

Run auth and proxy

cd services/auth && go run . then cd services/proxy && go run . in separate terminals.

5

Smoke test

make dev-smoke checks /health, /ready, auth failures, and the chat 501 stub.

Make targets

bash
make help              # list all targets
make compose-dev-up    # start infra/compose/dev stack
make compose-dev-down  # stop containers (keep volumes)
make compose-dev-reset # stop + delete volumes (fresh Postgres)
make compose-dev-ps    # container status
make compose-dev-logs  # tail dependency logs
make db-migrate        # apply pending migrations
make db-migrate-down   # roll back one step (dev only)
make db-seed           # idempotent dev org/agent/PAT
make dev-smoke         # end-to-end auth + proxy smoke

Verify the stack

bash
curl -s http://localhost:8080/health | jq
curl -s http://localhost:8081/ready | jq
docker compose -f infra/compose/dev/docker-compose.yml exec postgres pg_isready -U ibex -d ibex

Auth timeout on local machines

Set IBEX_AUTH_VALIDATE_TIMEOUT=2s on the proxy for local dev. The production default (50ms) is often too low for Argon2 verification and returns 503 SERVICE_DEGRADED before agent checks run.

Dev PAT from seed

After make db-seed, use the wire-form PAT from ADR-0007:

ibex_pat_00000000-0000-0000-0000-000000000004_LOCALDEVELOPMENTONLY

Fixed IDs: org …0001, agent …0003. Full values print in the seed script output.

Next steps

  • Environment variables — proxy, auth, Postgres, Redis
  • Proxy health — /health, /ready, /metrics contract

Was this page helpful?

Edit on GitHub

Last updated on

PreviousSecrets and keysNextKubernetes (production)

On this page

  • Compose services and ports
  • Boot sequence
  • Make targets
  • Verify the stack
  • Dev PAT from seed
  • Next steps
0%