---
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 <service>.yaml <service>
services:
  <servicename>:
    image: <image>:latest
    environment:
      TZ: America/Chicago
    volumes:
      - /DockerVol/<servicename>:/config          # use WITH placement constraint
      # - /data/nfs/znas/Docker/<servicename>:/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: <servicename>.netgrimoire.com
        caddy.reverse_proxy: <servicename>:<PORT>
        caddy.import: crowdsec
        caddy.import_1: authentik

        # --- Uptime Kuma ---
        kuma.<servicename>.http.name: <Service Name>
        kuma.<servicename>.http.url: https://<servicename>.netgrimoire.com

        # --- Homepage ---
        homepage.group: <Group>
        homepage.name: <Service Name>
        homepage.icon: <service>.png
        homepage.href: https://<servicename>.netgrimoire.com
        homepage.description: <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/<service>` | Config/state files. **Only valid when a placement constraint pins the service to a specific host.** |
| `/data/nfs/znas/Docker/<service>` | 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>.<monitor-type>.<field>: <value>
```

- `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.
