|
1 | 1 | --- |
2 | | -applyTo: ** |
3 | | -description: Copilot instructions for Local-Stack repository |
| 2 | +applyTo: "**" |
| 3 | +description: Minimal Copilot shim for Local-Stack; AGENTS.md is canonical. |
4 | 4 | --- |
5 | 5 |
|
6 | | -## Copilot instructions for Local-Stack repository |
| 6 | +## Local-Stack Copilot Shim |
7 | 7 |
|
8 | | -Goal: help an automated coding agent become productive quickly by describing the architecture, common developer workflows, repository conventions, and where to make safe, minimal changes. |
| 8 | +Primary instructions live in [AGENTS.md](../../AGENTS.md). Use that file as the canonical agent guide. |
9 | 9 |
|
10 | | -1) Big-picture architecture |
11 | | -- Historically, this repo used multiple Docker Compose files per service. We are migrating to modular Docker Swarm stacks to deploy the environment declaratively across local and remote hosts. |
12 | | -- Service folders remain the source of truth for per-service configs: `traefik/`, `apisix/`, `observability/`, `postgres/`, `mongo/`, `redis/`, `growthbook/`, `portainer/`, `anitrend/`, and `on-the-edge/`. |
13 | | -- Traefik is the edge router/TLS terminator; routing and middleware live in `traefik/config` and service-level labels. |
14 | | -- Observability lives under `observability/` (`grafana/`, `prometheus/`, `loki/`, `tempo/`, `otel/`). |
15 | | -- Target stack split (Swarm): |
16 | | - - Infrastructure: Traefik, Portainer, APISIX (gateway + etcd + dashboard), Postgres, Mongo, Redis. |
17 | | - - Observability: Prometheus, Grafana, Loki, Tempo, OTel Collector. |
18 | | - - Platform: GrowthBook (dashboard + proxy), AniTrend apps/services, and other application-facing components. |
| 10 | +## Critical Guardrails |
19 | 11 |
|
20 | | -2) Key files and conventions (referenced in tasks) |
21 | | -- Compose files: search for `**/docker-compose*.yml` or `**/docker-compose*.yaml`. Each service folder usually contains a compose file and an accompanying `.env.example`. |
22 | | -- Environment files: the repo expects service-specific `.env` files created from `.env.example` (e.g., `traefik/.env.example`). CI jobs often copy `.env.example` -> `.env` for validation. |
23 | | -- Traefik config: `traefik/config/traefik.yml` and `traefik/config/dynamic.yml` are authoritative for routing. When changing hostnames or ports update these files. |
24 | | -- Observability provisioning: `observability/grafana/config/provisioning/` contains dashboards and datasources that should be updated together with any metric source changes. |
25 | | -- Swarm stacks: new modular Swarm stack files will live under a `stacks/` directory (planned names: `infrastructure.yml`, `observability.yml`, `platform.yml`). The legacy root-level `swarm.*.yml` files are deprecated—do not edit or use them. |
| 12 | +- Do not edit generated rendered stack outputs. |
| 13 | +- Do not use or modify deprecated root-level `swarm.*.yml` files. |
| 14 | +- Prefer service-local source changes (`docker-compose*.yml`, `swarm.fragment.yml`, `.env.example`) and then regenerate/sync stacks. |
| 15 | +- Keep exposed services on `traefik-public` with correct Traefik labels. |
| 16 | +- Keep secrets out of source; use environment variables and follow [docs/Managing Secrets.md](../../docs/Managing%20Secrets.md). |
26 | 17 |
|
27 | | -3) Developer workflows and commands (explicit) |
28 | | -- Preferred (Swarm, modular): |
29 | | - - Initialize Swarm (once per host): `docker swarm init`. |
30 | | - - Create shared overlay network (once): `docker network create --driver=overlay --attachable traefik-public`. |
31 | | - - Deploy stacks: |
32 | | - - `docker stack deploy -c stacks/infrastructure.yml infrastructure` |
33 | | - - `docker stack deploy -c stacks/observability.yml observability` |
34 | | - - `docker stack deploy -c stacks/platform.yml platform` |
35 | | - - Verify: `docker stack services <stack>` and Portainer UI. Tear down with `docker stack rm <stack>`. |
36 | | -- Legacy local-only (Compose): still available per service for iterative work until migration completes. |
37 | | - - Example: `cd traefik && cp .env.example .env && docker compose up -d` |
38 | | - - Observability (legacy): `cd observability && for d in grafana prometheus loki tempo otel; do cp $d/.env.example $d/.env; done && docker compose up -d` |
39 | | -- Validation (CI/dev): |
40 | | - - Compose syntax: `docker compose -f <path> config`. |
41 | | - - YAML linting: `yamllint <file>`. |
42 | | - - YAML parsing validation: `yq e '.' <file> >/dev/null` (prefer this in scripts/workflows for fast syntax checks). |
43 | | - - Dockerfile linting: `hadolint` via container. |
| 18 | +## Canonical References |
44 | 19 |
|
45 | | -4) What to change and where (safe-scoped edits) |
46 | | -- Service-scoped config: edit the service folder (`docker-compose.yml`, `.env.example`, and config files) as before. These feed into both Compose and Swarm stacks. |
47 | | -- Swarm stacks (preferred for deployment): add/update files under `stacks/` to include or configure services. Keep stacks modular by function: infrastructure, observability, platform. |
48 | | -- Cross-cutting routing or hostnames: update `traefik/config/dynamic.yml` and service labels (`traefik.http.routers.*`). |
49 | | -- Do NOT edit or use root-level `swarm.*.yml`—they are deprecated remnants of an initial attempt. |
50 | | - |
51 | | -5) Integration points and external dependencies |
52 | | -- Networks: Under Swarm, all exposed services attach to a shared external overlay network named `traefik-public` (create once). Compose continues to create local bridge networks for ad-hoc local runs. |
53 | | -- Routing: Traefik discovers services via Docker metadata and labels on the shared network. |
54 | | -- External dependencies: none hard-coded; some components expect valid certificates in `traefik/certs` and secrets via `.env`. |
55 | | - |
56 | | -6) Common pitfalls and agent guidance |
57 | | -- Ensure the external overlay network `traefik-public` exists before deploying stacks. |
58 | | -- Avoid Compose-only keys in Swarm stacks: no `container_name`, no `restart` (use `deploy.restart_policy`), and no `build` (images must be pre-built/pulled). |
59 | | -- Prefer `deploy` settings in Swarm: `mode` (global/replicated), `placement.constraints` (e.g., `node.role == manager`), resource limits, and optional `restart_policy`. |
60 | | -- Use `env_file` to load per-service `.env`; consider Docker secrets/config for sensitive values in future iterations. |
61 | | -- `depends_on` in Swarm affects start order only; add healthchecks for critical readiness if needed. |
62 | | -- Do not assume `.env` files exist; if adding new variables, update `.env.example` and docs. |
63 | | -- When updating observability dashboards or Prometheus scrape configs, update provisioning under `observability/*/config` and Grafana datasources. |
64 | | - |
65 | | -7) Code and content patterns to preserve |
66 | | -- Service-level folder structure; keep related config colocated. |
67 | | -- Volume mounts and named volumes for persistence. |
68 | | -- Traefik labels on services for routing; keep consistent naming and middleware reuse. |
69 | | - |
70 | | -8) Where to run tests/builds |
71 | | -- There are no application unit tests in this repo; validation is through Compose validation and scanning workflows (`.github/workflows/docker-lint.yml` and `.github/workflows/docker-scan.yml`). |
72 | | -- For Swarm changes, perform a dry deploy on a local single-node swarm and verify `docker stack services` shows healthy tasks; prefer incremental stack updates. |
73 | | - |
74 | | -9) If you are unsure |
75 | | -- Prefer small, reversible edits: add/update `stacks/<module>.yml` rather than touching many service configs at once. Keep Compose changes minimal and documented. |
76 | | -- Open a PR with CI results and a brief manual verification plan (Swarm deploy steps and expected endpoints). |
77 | | - |
78 | | -10) Acceptance criteria for the Swarm migration (initial phase) |
79 | | -- Single-node Swarm deploys of `infrastructure`, `observability`, and `platform` stacks succeed. |
80 | | -- All exposed services are reachable via Traefik on the shared `traefik-public` network. |
81 | | -- No Swarm stack uses `container_name`, `restart`, or `build` keys. |
82 | | -- Critical data volumes (e.g., Traefik certs, Portainer data, databases) are persisted via named volumes (external where reusing existing data). |
83 | | - |
84 | | -Deprecated: root-level `swarm.*.yml` files. Do not use or update; they will be archived once new `stacks/*.yml` files are introduced. |
85 | | - |
86 | | -If anything above is unclear or you want examples added (e.g., exact `docker compose config` output handling), tell me which area to expand and I'll iterate. |
| 20 | +- [AGENTS.md](../../AGENTS.md) |
| 21 | +- [README.md](../../README.md) |
| 22 | +- [stacks/README.md](../../stacks/README.md) |
0 commit comments