Skip to main content

Infra Bootstrap Gate

Use this when application services depend on infrastructure initialized by a short setup command.

Typical examples: bringing up local Docker Compose infra, scaling down conflicting Kubernetes pods, or generating temporary fixtures.

Baseline config​

{
  "services": {
    "infra-up": {
      "kind": "oneshot",
      "cmd": ["docker", "compose", "-f", "./infra/compose.yml", "up", "-d"]
    },
    "api": {
      "cmd": ["pnpm", "--dir", "services/api", "dev"],
      "dependsOn": ["infra-up"],
      "ready": {
        "type": "http",
        "url": "http://127.0.0.1:3000/health"
      }
    },
    "worker": {
      "cmd": ["pnpm", "--dir", "services/worker", "dev"],
      "dependsOn": ["infra-up"]
    }
  }
}

Why it works​

  • one explicit bootstrap step controls infra preconditions
  • app services stay blocked until bootstrap exits successfully
  • setup logic is visible in plan and logs, not hidden in shell scripts

Guardrails​

  • keep bootstrap commands idempotent
  • fail fast on bootstrap errors
  • do not encode long-running daemons as oneshot bootstrap services

Common mistake​

Putting teardown in the same oneshot command chain as startup often creates hard-to-debug partial states.

Keep teardown explicit (Ctrl+C flow + dedicated scripts) and verify Commands for shutdown behavior.