Local-Stack is migrating from per-service Compose to modular Docker Swarm stacks. Keep agent guidance short, link to the canonical docs, and prefer editing the owning service or stack source instead of duplicating context here.
- Service folders are the source of truth for config:
traefik/,apisix/,observability/,postgres/,mongo/,redis/,growthbook/,portainer/,anitrend/,on-the-edge/,edge-graphql/,website/, andbeszel/. - Generated Swarm stacks live in
stacks/. Do not edit the rendered stack output directly; regenerate with./stackctl.sh generateor sync with./stackctl.sh sync. See stacks/README.md. - Deprecated root-level
swarm.*.ymlfiles are not used for deployment.
- For full-environment deploys and validation, follow stacks/README.md and the
./stackctl.shworkflow. - For service-local changes, update the service folder's
docker-compose.yml,swarm.fragment.yml, and.env.exampletogether when needed. - Keep exposed services attached to the shared
traefik-publicnetwork and route them with Traefik labels and traefik/config/dynamic.yml. - Update Grafana provisioning under observability/grafana/config/provisioning/ when dashboards or datasources change.
- project-local-stack-overview for repo structure, stack ownership, and Swarm migration context.
- project-stackctl-changes for safe, portable edits to
stackctl.sh. - project-tools-python-utilities for Python utility changes under
tools/.
- Prefer pinned GHCR tags; avoid
latest. - Do not assume
.envfiles exist. If a new variable is needed, update the matching.env.example. - For edge-facing apps, include Traefik router/service labels and a healthcheck that matches the exposed endpoint.
- Keep secrets out of source; prefer environment variables and the guidance in docs/Managing Secrets.md.