Skip to content
chant Docs Demo

Operational Playbook

llms.txt lists every page for an agent
Optional: hand this page to your coding agentThe steps work by hand too.
Show the whole prompt
Read https://intentius.io/chant/lexicons/docker/operational-playbook/.
Run `npx chant lint src`, `npx chant build src --lexicon docker -o docker-compose.yml` and `docker compose config --quiet`, and fix what they report.
If a service fails, bring the stack up on the local Docker daemon, read `docker compose ps` and `docker compose logs <service>`, and tell me the cause from the page's error table and the fix.
Open a pull request with the fix. Do not run `docker compose down -v` or push an image.
Never deploy to a real cloud account or shared environment (with `chant run`, `chant components` or a platform's own CLI), approve (a pull request review, `chant approve` or `chant run approve`), override a policy denial (`chant approve policy-override`), or merge; never cut or publish a release (`chant release cut --yes` or `chant release publish`), push or delete a `ci/*` tag (`chant ci tick` pushes them), or change the value of an existing flag; never touch `.chant/allowed_signers` or `chant/lifecycle`.

Build & validate

Section titled “Build & validate”
StepCommandWhat it catches
Lint sourcechant lint src/Latest tags (DKRS001)
Buildchant build src --lexicon docker -o docker-compose.ymlPost-synth: unused volumes, SSH exposure, Dockerfile issues
Validate configdocker compose configCompose schema validation

Run lint on every edit, and build and docker compose config before deploying.

Bring up a stack

Section titled “Bring up a stack”
Terminal window
# Build
chant build src --lexicon docker -o docker-compose.yml


# Validate
docker compose config --quiet


# Start detached
docker compose up -d


# Watch logs
docker compose logs -f

Teardown

Section titled “Teardown”
Terminal window
# Stop containers (keep volumes)
docker compose down


# Stop and remove volumes
docker compose down -v

Debugging

Section titled “Debugging”
Terminal window
# Container status and health
docker compose ps


# Logs for a specific service
docker compose logs api
docker compose logs api --follow


# Exec into a running container
docker compose exec api sh


# Inspect a stopped container
docker compose run --rm api sh

Common error patterns

Section titled “Common error patterns”
SymptomLikely causeFix
service "x" depends on undefined service "y"depends_on references wrong nameMatch the TypeScript export name
Container exits immediatelyApp crash on startdocker compose logs <service>
Port already in useHost port conflictChange host port in ports:
Volume not persistingAnonymous volume vs named volumeUse volumename:/path not just /path
Service can’t reach anotherWrong hostnameUse the service name as hostname
required variable ... is not setMissing env var for env("X", { required: true })Set var in environment or .env

Health checks

Section titled “Health checks”

Add health checks to stateful services so dependents wait for readiness:

export const db = new Service({
  image: "postgres:16-alpine",
  healthcheck: {
    test: ["CMD-SHELL", "pg_isready -U myapp"],
    interval: "10s",
    timeout: "5s",
    retries: 5,
    start_period: "10s",
  },
});


export const api = new Service({
  image: "myapp:1.0",
  depends_on: {
    db: { condition: "service_healthy" },
  },
});

Production safety

Section titled “Production safety”
  • Pin image tags instead of :latest (DKRS001 / DKRD001 flags this)
  • Do not expose port 22 (DKRD003 flags this)
  • Set restart: "unless-stopped" or restart: "always" for long-running services
  • Keep persistent data in named volumes, not the container filesystem
  • Read secrets with env() and { required: true } instead of writing them in source ===

chant