4lt/docker-compose-cookbooks
1
0
Fork 0
mirror of https://github.com/nickyeoman/docker-compose-cookbooks.git synced 2026-09-04 02:46:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

document conventions and add lint script

Browse Source 
AGENTS.md: internal network pattern, ChangeThisPassword secrets convention,
_notes exemption, and a Known exceptions list (pihole, zammad-init,
compose-aio, VOL_PROJECTS nesting, mailu env_file, headscale config vars).
README.md: fix Preferred typo.
_docs/lint.py: checks every convention plus compose<->sample.env sync;
run with python3 _docs/lint.py.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
code
2026-07-16 06:25:05 +00:00
co-authored by Claude Fable 5
parent 340866f9f4
commit 102c207bfc
3 changed files with 183 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+15
View File
@@ -4,6 +4,7 @@
- Every stack has at least 3 files: `compose.yaml` (dockhand style), `sample.env`, `README.md`
- `_dev` = experimental, `_notes` = docs/minimal examples, no suffix = production-ready
- `_notes` stacks are exempt from all conventions below — they hold notes, example commands, or minimal compose files only
- Always references an external `proxy` network (managed by Nginx Proxy Manager; `docker network create proxy` once)
- Volumes use `${VOL_PATH:-/data}` as the base path (absolute `/data`, never `./data`); project directories use `${VOL_PROJECTS:-/data}`
- Timezone defaults to `America/Vancouver`, but only include if the container requires it.
@@ -18,6 +19,20 @@ networks:
proxy:
external: true
```
- Multi-service stacks also use a bridge network named `internal` (see `network.yml` at the repo root for the sample): databases and other backing services join `internal` only; the app service joins both `proxy` and `internal`
- Default secrets (passwords, keys, tokens) are always the literal `ChangeThisPassword` — same string everywhere so it is easy to grep. Users must change them; never ship a real-looking secret as a default
- Lint the repo with `python3 _docs/lint.py` before committing — it checks all of the conventions above
## Known exceptions
These deliberately violate the conventions above — do not "fix" them:
- `pihole` uses `network_mode: host` (it's a DNS server), so it has no `proxy` network
- `zammad_dev` `zammad-init` service hardcodes `restart: on-failure` (init container)
- `nextcloud/compose-aio.yaml` follows the upstream AIO layout: fixed container/volume names, no env templating, no proxy network
- `opencode` and `vscode` default `VOL_PROJECTS` to `${VOL_PATH:-/data}/projects` (nested default), not plain `/data`
- `mailu_dev` passes env via `env_file: .env`, so its sample.env holds vars the compose file never references
- `headscale_dev` sample.env documents `HEADSCALE_DOMAIN`/`HEADSCALE_URL` for the config file even though compose doesn't use them
## No CI/CD, no dependency management