From 860725a9bb193fad2ce217676d6962ca24076556 Mon Sep 17 00:00:00 2001 From: Administrator Date: Fri, 10 Apr 2026 19:53:31 +0000 Subject: [PATCH] docs: create Netgrimoire/Infrastructure/Docker_Template --- Netgrimoire/Infrastructure/Docker_Template.md | 205 ++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 Netgrimoire/Infrastructure/Docker_Template.md diff --git a/Netgrimoire/Infrastructure/Docker_Template.md b/Netgrimoire/Infrastructure/Docker_Template.md new file mode 100644 index 0000000..6ed094e --- /dev/null +++ b/Netgrimoire/Infrastructure/Docker_Template.md @@ -0,0 +1,205 @@ +--- +title: Docker Template +description: Swarm and Compose Template +published: true +date: 2026-04-10T19:53:21.433Z +tags: +editor: markdown +dateCreated: 2026-04-10T19:53:21.433Z +--- + +# Docker Swarm Template Standard — Netgrimoire + +## Template + +```yaml +# Run with docker stack deploy -c .yaml +services: + : + image: :latest + environment: + TZ: America/Chicago + volumes: + - /DockerVol/:/config # use WITH placement constraint + # - /data/nfs/znas/Docker/:/data # use for bulk/data or no constraint + networks: + - netgrimoire + deploy: + restart_policy: + condition: any + delay: 5s + max_attempts: 3 + window: 120s + placement: + constraints: + - node.platform.arch != aarch64 + - node.platform.arch != arm + labels: + # --- Caddy --- + caddy: .netgrimoire.com + caddy.reverse_proxy: : + caddy.import: crowdsec + caddy.import_1: authentik + + # --- Uptime Kuma --- + kuma..http.name: + kuma..http.url: https://.netgrimoire.com + + # --- Homepage --- + homepage.group: + homepage.name: + homepage.icon: .png + homepage.href: https://.netgrimoire.com + homepage.description: + + # --- DIUN --- + diun.enable: "true" + +networks: + netgrimoire: + external: true +``` + +--- + +## Rules + +### Forbidden Fields +Never use these at the service level: +- `version:` — deprecated in Compose v2+ +- `container_name:` — incompatible with Swarm replicas +- `restart:` — use `deploy.restart_policy` instead +- `depends_on:` — not supported in Swarm mode + +### Volume Path Rules + +| Path | When to Use | +|------|------------| +| `/DockerVol/` | Config/state files. **Only valid when a placement constraint pins the service to a specific host.** | +| `/data/nfs/znas/Docker/` | Data/bulk volumes, or any service without a specific hostname constraint | + +### Caddy Labels + +```yaml +caddy: service.netgrimoire.com +caddy.reverse_proxy: servicename:PORT +caddy.import: crowdsec +caddy.import_1: authentik +``` + +- `caddy.import_1` is required for the second import — duplicate YAML keys cause deploy errors +- `caddy.reverse_proxy` uses `servicename:PORT` (internal Docker DNS), never `{{upstreams PORT}}` +- No `https://` prefix on the `caddy:` address line +- Services managed by Caddyfile (static config) must **not** also have Caddy Docker labels — mixing causes caddy-docker-proxy to merge them into a malformed upstream pool + +### Networking + +- Default VIP mode for services that publish ports +- `endpoint_mode: dnsrr` for internal-only services (no published ports) — avoids Swarm VIP stale DNS +- **Never use `dnsrr` on services with published ports** — incompatible with ingress mesh routing + +### Placement Constraints + +**Architecture exclusions** (always include unless ARM-specific): +```yaml +constraints: + - node.platform.arch != aarch64 # Pi 4 reports aarch64 + - node.platform.arch != arm # Pi 3 reports arm +``` + +**Note:** Docker Swarm uses the kernel's arch string. Pi 4 reports `aarch64` not `arm64`. The constraint `!= arm64` does **not** exclude Pi 4s. + +Verified node architectures in Netgrimoire: +``` +DockerPi1: linux/aarch64 +docker3: linux/x86_64 +docker4: linux/x86_64 +docker5: linux/x86_64 +znas: linux/x86_64 +``` + +### Label Sections + +Labels are organized with comment dividers in this order: + +```yaml +labels: + # --- Caddy --- + # --- Uptime Kuma --- + # --- Homepage --- + # --- DIUN --- +``` + +Use map syntax (not list syntax) for labels. List syntax (`- key=value`) and map syntax (`key: value`) both work, but map syntax is the standard. + +--- + +## Services Without a UI + +Some services have no web interface and need no Caddy, Homepage, or Kuma labels: + +**Example: DIUN** +```yaml +deploy: + labels: + # --- DIUN --- + diun.enable: "true" +``` + +Services in this category: DIUN, background workers, one-shot jobs. + +--- + +## Kuma Label Format + +```yaml +kuma...: +``` + +- `unique-id` — must be unique across all services in the entire Swarm +- `monitor-type` — `http`, `tcp`, `ping`, `dns` +- Common fields: `name`, `url`, `interval`, `maxretries` + +Example: +```yaml +kuma.forgejo.http.name: Forgejo +kuma.forgejo.http.url: https://git.netgrimoire.com +``` + +--- + +## Homepage Label Format + +```yaml +homepage.group: Group Name +homepage.name: Display Name +homepage.icon: icon.png +homepage.href: https://service.netgrimoire.com +homepage.description: Short description +``` + +For services with widgets: +```yaml +homepage.widget.type: radarr +homepage.widget.url: http://radarr:7878 +homepage.widget.key: apikey +``` + +**Important:** Every `homepage.group` value must have a matching entry in `settings.yaml` with `style: column`, or the group will render full-width. + +--- + +## Secrets Approach + +Docker Swarm native secrets are preferred. For services that support `_FILE` env vars: + +```yaml +environment: + MY_PASSWORD_FILE: /run/secrets/my_password +secrets: + - my_password +``` + +Plain credentials in environment vars are acceptable as an interim approach for services that don't support `_FILE`. + +**Never use `env_file:` in Swarm stacks** — it's read by the Docker client at deploy time from the deploying machine, not injected into the container at runtime. Use `environment:` directly.