Skip to main content

Run Docker Compose Before Services

Use this recipe when part of your local stack is managed by Docker Compose, but your app processes still run directly on the host.

FlowLayer has no Docker-specific orchestration logic. It runs Docker commands like any other process command.

Pattern: oneshot bootstrap service​

Create a kind: "oneshot" service that runs docker compose up -d, then make app services depend on it.

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

What happens at runtime​

  • compose-up starts first and must exit with code 0.
  • api and worker are allowed to start after that dependency succeeds.
  • On graceful shutdown, stopCmd can run even if compose-up already exited.

Limits and precautions​

  • docker compose up -d finishing does not guarantee every container is app-ready.
  • Add readiness checks on your host services (http or tcp) so dependents do not race.
  • stopCmd is skipped in forced shutdown mode (second interrupt).
  • Keep Docker commands explicit and local-dev scoped.

Suggested ops flow​

  1. Run flowlayer-server -c ./flowlayer.jsonc.
  2. Confirm compose-up exited successfully.
  3. Watch api readiness before opening the frontend.
  4. Use graceful stop to ensure docker compose down is executed.

For additional readiness tuning, see Add Readiness Checks.