kevinveenbirkenbachandClaude Opus 4.7
16bdbf03d7
Three classes of drift cleaned up across 85 .md files:
- Em-dashes: replaced ` — ` with the contextually correct separator
(colon for `term: explanation`, period to split clauses across
sentences/source lines, parentheses for asides, semicolon for
tight-linked continuations). Two intentional exceptions remain
in `docs/contributing/documentation.md` (the rule literal) and
inside a fenced ```sh block in `docs/contributing/actions/debugging/ci.md`.
- SPOT self-labels: rewrote "This is the SPOT for X" to describe
the subject directly ("This directory holds X" / "This file
describes X"). Cross-references to other artefacts' canonical
role remain unchanged.
- Heading-emoji position: moved leading-emoji headings (`# 🧩 Title`)
to trailing position (`# Title 🧩`) per the headline rule that
emojis MUST come after the title text.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.1 KiB
Network utils 🕸️
Reusable task files for creating Docker networks in a uniform way.
Both helpers derive the docker-side network name from role_id | get_entity_name and the subnet from meta/server.yml.networks.local.subnet, so the name and the subnet pinning live in exactly one place.
Ad-hoc community.docker.docker_network calls or docker network create / container network create shell-outs in role tasks are forbidden by test_network_create_via_util.py.
When to use which 🧭
create.yml: network only, no compose-up
Use when the role still has work to do between the network creation and the compose-up.
Examples: copy entrypoint.sh / healthcheck.sh into the instance directory before the container starts, render additional configs, pre-attach other resources.
Also the right choice when pre-creating several foreign networks in a loop (e.g. prometheus's native_metrics_apps pre-create), where firing the compose handler per iteration would be wrong.
Required var:
network_role_id: the role whose network to create. Name and subnet are derived from it.
- include_tasks: "{{ [playbook_dir, 'roles/sys-svc-compose/tasks/utils/network/create.yml'] | path_join }}"
vars:
network_role_id: "{{ application_id }}"
routine.yml: wrapper with immediate compose-up
Use when the role is a self-contained single-container service whose only pre-condition for compose-up is its own network (e.g. svc-db-mariadb, svc-db-postgres, svc-ai-ollama).
The wrapper loads the docker-python deps, calls create.yml for the role's own network (via application_id), and then re-includes sys-svc-compose with docker_compose_flush_handlers: true so the compose-up fires right after.
- include_tasks: "{{ [playbook_dir, 'roles/sys-svc-compose/tasks/utils/network/routine.yml'] | path_join }}"
vars:
docker_compose_flush_handlers: true
Decision rule 📌
Pick routine.yml when "create network → compose-up immediately" is the entire pre-condition chain.
Pick create.yml in every other case.