---

name: local-compose description: "Guides Instill Core local Docker Compose startup, service lifecycle, ports, logs, and overlay debugging workflows." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Local Compose

Use this route when the user wants the local platform stack started, stopped, inspected, or debugged with Docker Compose.

Use this when the request mentions

• make run, make compose-run, or make compose-dev.
• make down, make start, make stop, make ps, make logs, make pull, make images, or make top.
• Docker Compose files such as docker-compose.yml, docker-compose-dev.yml, docker-compose-nvidia.yml, or docker-compose-observe.yml.
• Service port, health, or container-name questions for the local stack.
• GPU-vs-CPU compose selection or observability overlays.

What belongs here

• Starting and stopping the stack.
• Inspecting service status, logs, and ports.
• Understanding the dev overlay, GPU overlay, and observability overlay.
• Checking the main health endpoints and service dependencies.

What does not belong here

• Helm or Kubernetes deployment; use helm-deployment.
• Dummy model build/push or model initialization; use integration-tests.
• Version bump or release automation; use release-maintenance.
• Backend source code edits in sibling service repositories.

Core workflow

1. Run ../../scripts/check-toolchain.sh --mode compose --repo-root <checkout>.
2. Confirm the intended edition and overlay set in ../../references/configuration.md.
3. Use make run for the default local stack or make compose-dev for the dev overlay.
4. Use make ps, make logs, make stop, make start, make pull, make images, and make top to inspect or manage the stack.
5. Use make down before retrying a failed run so stale containers and volumes do not interfere.

Quick decision cues

• Choose make run for the default local stack.
• Choose make compose-dev when you want the debug overlay and the published backend ports.
• Choose OBSERVE_ENABLED=true make run when you need Grafana, Prometheus, Tempo, Loki, and the collector overlay.
• On GPU-capable hosts, remember that the Makefile auto-selects the NVIDIA compose path and therefore expects yq.
• If the same stack was interrupted earlier, clear it with make down before trying again.

Common mistakes

• Assuming the backend service source code lives in this repository.
• Forgetting to inspect the active .env file and secrets files before the first boot.
• Forgetting that the GPU overlay is selected automatically when nvidia-smi is present.
• Skipping make down after a half-failed run and then reading stale logs from the wrong containers.

If the request is mixed or unclear

• Choose this route if the user wants the container stack up or down, even if they also mention ports or logs.
• If the user is talking about chart rendering or Kubernetes, send them to the Helm route instead.
• If the user is talking about dummy models or registry population, send them to the integration-tests route instead.
• When the user only needs the command surface, the Makefile targets in this route are usually enough.

Read these references

• workflows for the command map and local-stack startup sequence.
• troubleshooting for Docker, port, GPU, and env-file failures.
• configuration for ports, health probes, and overlays.
• check-toolchain.sh before the first retry.

Useful commands

• make run launches the stack with the default edition.
• make compose-run EDITION=docker-ce:test matches the Compose integration-test edition.
• make compose-dev adds the development overlay.
• OBSERVE_ENABLED=true make run adds the observability overlay.

Exit criteria

A future agent should be able to start the stack, confirm the main ports and health probes, and cleanly stop the stack without reopening the original repository docs.