| name | local-docker-k3d-alignment |
| description | When adding or changing preconditions, cleanup steps, or env usage for local Docker Compose or local k3d, keep both in sync where they share resources (e.g. infra/config/local/*.env). |
Local Docker vs k3d alignment
When to use
When modifying Makefile targets or scripts that:
- Start or stop local Docker Compose services or the local k3d cluster
- Read or write
infra/config/local/*.env (generated from infra/env/classification/ via scripts/local-env/setup.sh, not from .env.example stubs)
- Check for “running” state before running env clean, setup, or reset
Rule
Keep Docker and k3d local behavior aligned where they share resources (e.g. env files). If a target aborts when Docker containers are running, consider aborting when the k3d cluster is running when the same env files are in use. Full teardown / clean targets should also tear down the k3d cluster, not only Docker.
Commands that should consider k3d: (1) Guards: any target that refuses to run while Docker is up and touches shared env (e.g. local_env_clean) should also refuse while k3d is up. (2) Teardown: any "clean" or "full teardown" target (e.g. local_clean) should run local_k3d_down so both Docker and k3d are stopped. (3) Docs: where local env or k3d is described, note shared env and that local_clean tears down both.
Do
infra/config/local/*-sidecar.env vs apps/*/sidecar/.env: local_env_setup generates both with merge-env: infra files use --profile local_docker (Compose env_file); app sidecar/.env files use --profile dev (host npm). They are independent outputs, not copies; do not assume byte parity.- Guard
local_env_clean on both Docker Compose containers and the k3d cluster; document that both use infra/config/local/*.env (Postgres: single db.env; Valkey: valkey-source-only.env, valkey.env).
- Include k3d in "full teardown" targets:
local_clean should run local_k3d_down so Docker, k3d, and test/E2E are all torn down.
- When adding a precondition or cleanup step that touches
infra/config/local/*.env or “running” state, apply the same logic to both Docker and k3d (or document why they differ).
Don't
- Don’t add Docker-only or k3d-only guards for shared env without considering the other (e.g. cleaning env while k3d is up leaves the cluster with stale secrets).
Examples
- local_env_clean: Aborts if Boilerplate local containers are running (
make local_down) and also if the k3d cluster is running (make local_k3d_down).
- local_clean: Full teardown runs
local_down, local_down_volumes, local_k3d_down (idempotent if cluster is gone), and test_clean so both Docker and k3d are stopped.
- Docs:
local_env_setup and local_k3d_up both consume infra/config/local/*.env; mention this where describing local env or k3d setup. Document that make local_clean tears down k3d as well as Docker.
