fix traefik-docker.network label as best-practice for all templates

AGENTS.md

@@ -288,6 +288,17 @@ class ComposeModule(Module):
 - **Static Files**: Non-`.j2` files copied as-is.
 - **Sanitization**: Auto-sanitized (single blank lines, no leading blanks, trimmed whitespace, single trailing newline).
 
+### Docker Compose Best Practices
+
+**Traefik Integration:**
+
+When using Traefik with Docker Compose, the `traefik.docker.network` label is **CRITICAL** for stacks with multiple networks. When containers are connected to multiple networks, Traefik must know which network to use for routing.
+
+**Implementation:**
+- ALL templates using Traefik MUST follow the patterns in `archetypes/compose/traefik-v1.j2` (standard mode) and `archetypes/compose/swarm-v1.j2` (swarm mode)
+- These archetypes are the authoritative reference for correct Traefik label configuration
+- The `traefik.docker.network={{ traefik_network }}` label must be present in both standard `labels:` and `deploy.labels:` sections
+
 ### Variables
 
 **Precedence** (lowest to highest):

archetypes/compose/swarm-v1.j2

@@ -16,6 +16,7 @@ services:
       {% if traefik_enabled %}
       labels:
         - traefik.enable=true
+        - traefik.docker.network={{ traefik_network }}
         - traefik.http.services.{{ service_name }}-web.loadBalancer.server.port={{ test_port }}
         - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}-web
         - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
@@ -37,6 +38,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}-web.loadBalancer.server.port={{ test_port }}
       - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}-web
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)

archetypes/compose/traefik-v1.j2

@@ -5,6 +5,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}-web.loadBalancer.server.port={{ test_port }}
       - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}-web
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)

library/compose/alloy/compose.yaml.j2

@@ -36,6 +36,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network | default("traefik") }}
       - traefik.http.services.{{ service_name | default("alloy") }}.loadbalancer.server.port=12345
       - traefik.http.services.{{ service_name | default("alloy") }}.loadbalancer.server.scheme=http
       - traefik.http.routers.{{ service_name | default("alloy") }}-http.service={{ service_name | default("alloy") }}

library/compose/authentik/compose.yaml.j2

@@ -22,6 +22,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}.loadbalancer.server.port=9000
       - traefik.http.services.{{ service_name }}.loadbalancer.server.scheme=http
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)

library/compose/checkmk/compose.yaml.j2

@@ -19,6 +19,7 @@ services:
       - frontend
     labels:
       - traefik.enable=true
+      - traefik.docker.network=frontend
       - traefik.http.services.checkmk.loadbalancer.server.port=5000
       - traefik.http.services.checkmk.loadbalancer.server.scheme=http
       - traefik.http.routers.checkmk.service=checkmk

library/compose/dockge/compose.yaml.j2

@@ -11,6 +11,7 @@ services:
     # --> (Optional) When using traefik
     # labels:
     #   - traefik.enable=true
+    #   - traefik.docker.network=frontend
     #   - traefik.http.routers.dockge-http.entrypoints=web
     #   - traefik.http.routers.dockge-http.rule=Host(`your-dockge-fqdn`)  # <-- Change this to your FQDN
     #   - traefik.http.routers.dockge-https.entrypoints=websecure

library/compose/gitea/compose.yaml.j2

@@ -21,6 +21,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}.loadbalancer.server.port=3000
       - traefik.http.services.{{ service_name }}.loadbalancer.server.scheme=http
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)

library/compose/gitlab/compose.yaml.j2

@@ -26,6 +26,7 @@ services:
 {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ container_name }}.loadbalancer.server.port=80
       - traefik.http.services.{{ container_name }}.loadbalancer.server.scheme=http
       - traefik.http.routers.{{ container_name }}-http.service={{ container_name }}

library/compose/grafana/compose.yaml.j2

@@ -22,6 +22,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}.loadbalancer.server.port=3000
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}

library/compose/homer/compose.yaml.j2

@@ -22,6 +22,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}.loadbalancer.server.port=8080
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}

library/compose/influxdb/compose.yaml.j2

@@ -29,6 +29,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network | default('traefik') }}
       - traefik.http.services.{{ service_name | default('influxdb') }}.loadbalancer.server.port=8086
       - traefik.http.services.{{ service_name | default('influxdb') }}.loadbalancer.server.scheme=http
       - traefik.http.routers.{{ service_name | default('influxdb') }}-http.rule=Host(`{{ traefik_host }}`)

library/compose/loki/compose.yaml.j2

@@ -13,6 +13,7 @@ services:
     # --> (Optional) When using traefik...
     # labels:
     #   - traefik.enable=true
+    #   - traefik.docker.network=frontend
     #   # -- Traefik Services
     #   - traefik.http.services.loki.loadbalancer.server.port=3100
     #   # -- Traefik Routers

library/compose/n8n/compose.yaml.j2

@@ -42,6 +42,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network | default('traefik') }}
       - traefik.http.routers.{{ service_name | default('n8n') }}-http.rule=Host(`{{ traefik_host | default('n8n.home.arpa') }}`)
       - traefik.http.routers.{{ service_name | default('n8n') }}-http.entrypoints={{ traefik_entrypoint | default('web') }}
       {% if traefik_tls_enabled %}

library/compose/nextcloud/compose.yaml.j2

@@ -28,6 +28,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network | default('traefik') }}
       - traefik.http.services.{{ service_name | default('nextcloud') }}.loadbalancer.server.port=80
       - traefik.http.routers.{{ service_name | default('nextcloud') }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name | default('nextcloud') }}-http.entrypoints={{ traefik_entrypoint | default('web') }}

library/compose/nginx/compose.yaml.j2

@@ -10,6 +10,7 @@ services:
       {% if traefik_enabled %}
       labels:
         - traefik.enable=true
+        - traefik.docker.network={{ traefik_network | default('traefik') }}
         - traefik.http.services.{{ container_name | default('nginx') }}.loadbalancer.server.port=80
         - traefik.http.routers.{{ container_name | default('nginx') }}-http.rule=Host(`{{ traefik_host }}`)
         - traefik.http.routers.{{ container_name | default('nginx') }}-http.entrypoints={{ traefik_entrypoint | default('web') }}
@@ -34,6 +35,7 @@ services:
     {% if traefik_enabled and not swarm_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network | default('traefik') }}
       - traefik.http.services.{{ container_name | default('nginx') }}.loadbalancer.server.port=80
       - traefik.http.routers.{{ container_name | default('nginx') }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ container_name | default('nginx') }}-http.entrypoints={{ traefik_entrypoint | default('web') }}

library/compose/openwebui/compose.yaml.j2

@@ -22,6 +22,7 @@ services:
       - frontend
     labels:
       - traefik.enable=true
+      - traefik.docker.network=frontend
       - traefik.http.routers.openwebui.rule=Host(`openwebui.example.com`)
       - traefik.http.routers.openwebui.entrypoints=websecure
       - traefik.http.routers.openwebui.tls=true

library/compose/pihole/compose.yaml.j2

@@ -87,6 +87,7 @@ services:
       {% if traefik_enabled %}
       labels:
         - traefik.enable=true
+        - traefik.docker.network={{ traefik_network }}
         - traefik.http.services.{{ service_name }}-web.loadBalancer.server.port=80
         - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}-web
         - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
@@ -103,6 +104,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}-web.loadBalancer.server.port=80
       - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}-web
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)

library/compose/portainer/compose.yaml.j2

@@ -25,6 +25,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}.loadbalancer.server.port=9000
       - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)

library/compose/semaphoreui/compose.yaml.j2

@@ -21,6 +21,7 @@ services:
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}.loadbalancer.server.port=3000
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}

library/compose/wazuh/compose.yaml.j2

@@ -113,6 +113,7 @@ services:
     # --> (Optional) When using traefik
     # labels:
     #   - traefik.enable=true
+    #   - traefik.docker.network=frontend
     #   - traefik.http.routers.wazuh-prod-1-https.entrypoints=websecure
     #   - traefik.http.routers.wazuh-prod-1-https.rule=Host(`wazuh-prod-1.srv-prod-1.home.clcreative.de`)
     #   - traefik.http.routers.wazuh-prod-1-https.tls=true

library/compose/whoami/compose.yaml.j2

@@ -21,6 +21,7 @@ services:
         condition: on-failure
       labels:
         - traefik.enable=true
+        - traefik.docker.network={{ traefik_network }}
         - traefik.http.services.{{ service_name }}.loadbalancer.server.port=80
         - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
         - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}
@@ -33,6 +34,7 @@ services:
     {% else %}
     labels:
       - traefik.enable=true
+      - traefik.docker.network={{ traefik_network }}
       - traefik.http.services.{{ service_name }}.loadbalancer.server.port=80
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}