From 9fccb436e3152d19e3f3eba26e01c3c24e3497a7 Mon Sep 17 00:00:00 2001 From: traveler Date: Fri, 10 Apr 2026 07:53:27 -0500 Subject: [PATCH] Delete Netgrimoire/infrastructure/swarm-template/swarm-template-standard.md --- .../swarm-template/swarm-template-standard.md | 195 ------------------ 1 file changed, 195 deletions(-) delete mode 100644 Netgrimoire/infrastructure/swarm-template/swarm-template-standard.md diff --git a/Netgrimoire/infrastructure/swarm-template/swarm-template-standard.md b/Netgrimoire/infrastructure/swarm-template/swarm-template-standard.md deleted file mode 100644 index b2988d5..0000000 --- a/Netgrimoire/infrastructure/swarm-template/swarm-template-standard.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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.