AI coding agents can produce useful Docker Compose files, but the best files are explicit, boring, and easy to review. A good Compose file should show what runs, what is public, what depends on what, and which values must be supplied at deploy time.

Review rules

Use stable service names such as web, api, worker, db, and cache. Keep only public app services in ports. Put environment variable names in environment, not secret values. Add health checks to services that receive traffic. Prefer managed-service annotations for production databases, caches, and LLM dependencies. Declare service dependencies with depends_on when startup order matters.

Good service pattern

services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL
      - LLM_API_KEY
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    depends_on:
      db:
        condition: service_started

  db:
    image: postgres:17
    x-defang-postgres: true

Note: The image field (e.g., postgres:17) is required — Defang uses it to determine the managed service version. Locally, docker compose up uses the same image as a regular container. The x-defang- annotations are only interpreted by Defang during cloud deployment.

Secrets handling

Do not embed credentials in the Compose file. Use defang config set SECRET_NAME to store sensitive values. The environment variable name stays in the Compose file; the value is stored securely.

What to avoid

Avoid generated passwords, public database ports, unexplained services, missing Dockerfiles, and environment variables with real credentials. Avoid overly clever YAML that makes the app harder for the human to audit.

Recommended next step

Use compose.new to generate or validate the Compose file, then deploy the reviewed file with Defang.

For a fuller agent workflow, install Defang Agent Skills. They give compatible coding agents Defang’s estimate, deploy, and debug workflows after the Compose file is ready.