Skip to content

AGENTS.md

Latest commit

 

History

History
37 lines (26 loc) · 3.19 KB

AGENTS.md

File metadata and controls

37 lines (26 loc) · 3.19 KB
Raw

Local-Stack Agent Guide

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.

Source Of Truth

  • Service folders are the source of truth for config: traefik/, apisix/, observability/, postgres/, mongo/, redis/, growthbook/, unleash/, portainer/, anitrend/, on-the-edge/, edge-graphql/, website/, and beszel/.
  • Generated Swarm stacks live in stacks/. Do not edit the generated stack output directly; regenerate with stackctl generate or, on the compatibility path, ./stackctl.sh generate. Drift between compose sources and committed stacks is validated with stackctl sync (drift check only: it never generates or deploys). See stacks/README.md.
  • Deprecated root-level swarm.*.yml files are not used for deployment.

How To Work

  • For full-environment deploys and validation, follow stacks/README.md and prefer the stackctl CLI (configured by the committed .stackctl). Root ./stackctl.sh is retained only as a compatibility fallback for the current Doco-CD Linux runtime.
  • For service-local changes, update the service folder's docker-compose.yml, swarm.fragment.yml, and .env.example together when needed.
  • Swarm customizations go in swarm.fragment.yml: deploy (mode, replicas, placement, resources), network aliases, DNS overrides, and any key that only applies under docker stack deploy. Keep docker-compose.yml portable — it should work standalone with docker compose up where possible.
  • Keep exposed services attached to the shared traefik-public network 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 Skills

Change Rules

  • Prefer pinned GHCR tags; avoid latest.
  • Do not assume .env files 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.

Good Starting Docs