local-docker-k3d-alignment

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.