new archetypes

archetypes/compose/configs-v1.j2

@@ -0,0 +1,20 @@
+{#
+  Archetype: toplevel-configs-v1
+  
+  Description:
+    Swarm configs definition from file source.
+  
+  Approach:
+    - Only applies to swarm mode
+    - Reads config from file at deploy time
+    - Configs are immutable once created
+  
+  Usage:
+    Use with service-configs-v1 for configuration file management.
+    Create configuration file before deploying stack.
+#}
+{% if swarm_enabled %}
+configs:
+  {{ config_name }}:
+    file: ./config/app.yaml
+{% endif %}

archetypes/compose/network-v1.j2

@@ -1,51 +0,0 @@
----
-services:
-  test_service:
-    {% if network_mode == 'host' %}
-    network_mode: host
-    {% else %}
-    networks:
-      {% if traefik_enabled %}
-      {{ traefik_network }}:
-      {% endif %}
-      {% if network_mode == 'macvlan' %}
-      {{ network_name }}:
-        ipv4_address: {{ network_macvlan_ipv4_address }}
-      {% elif network_mode == 'bridge' %}
-      {{ network_name }}:
-      {% endif %}
-    {% endif %}
-
-{% if network_mode != 'host' %}
-networks:
-  {% if network_mode == 'macvlan' %}
-  {{ network_name }}:
-    {% if network_external %}
-    external: true
-    {% else %}
-    driver: macvlan
-    driver_opts:
-      parent: {{ network_macvlan_parent_interface }}
-    ipam:
-      config:
-        - subnet: {{ network_macvlan_subnet }}
-          gateway: {{ network_macvlan_gateway }}
-    name: {{ network_name }}
-    {% endif %}
-  {% elif network_mode == 'bridge' and network_external %}
-  {{ network_name }}:
-    external: true
-  {% elif network_mode == 'bridge' and not network_external %}
-  {{ network_name }}:
-    {% if swarm_enabled %}
-    driver: overlay
-    attachable: true
-    {% else %}
-    driver: bridge
-    {% endif %}
-  {% endif %}
-  {% if traefik_enabled %}
-  {{ traefik_network }}:
-    external: true
-  {% endif %}
-{% endif %}

archetypes/compose/networks-v1.j2

@@ -0,0 +1,50 @@
+{#
+  Archetype: networks-v1
+  
+  Description:
+    Consolidated top-level networks section supporting multiple modes:
+    - Bridge: Simple bridge network for standalone deployments
+    - External: Reference pre-existing networks
+    - Macvlan: L2 network access with static IP assignment
+    - Swarm: Overlay networks for multi-node swarm clusters
+  
+  Approach:
+    - Conditionally creates network based on network_mode or network_enabled
+    - Supports external networks (network_external flag)
+    - Macvlan includes IPAM configuration
+    - Swarm mode uses overlay driver with attachable option
+    - Always includes Traefik network as external when enabled
+  
+  Usage:
+    Use as the single networks archetype for all deployment types.
+    Adapts based on network_mode, swarm_enabled, and network_external variables.
+#}
+{% if network_enabled or traefik_enabled %}
+networks:
+  {% if network_enabled %}
+  {{ network_name }}:
+    {% if network_external %}
+    external: true
+    {% else %}
+    {% if network_mode == 'macvlan' %}
+    driver: macvlan
+    driver_opts:
+      parent: {{ network_macvlan_parent_interface }}
+    ipam:
+      config:
+        - subnet: {{ network_macvlan_subnet }}
+          gateway: {{ network_macvlan_gateway }}
+    name: {{ network_name }}
+    {% elif swarm_enabled %}
+    driver: overlay
+    attachable: true
+    {% else %}
+    driver: bridge
+    {% endif %}
+    {% endif %}
+  {% endif %}
+  {% if traefik_enabled %}
+  {{ traefik_network }}:
+    external: true
+  {% endif %}
+{% endif %}

archetypes/compose/ports-v1.j2

@@ -1,65 +0,0 @@
----
-services:
-  {{ service_name }}:
-    image: {{ test_image }}
-    {% if swarm_enabled %}
-    deploy:
-      mode: {{ swarm_placement_mode }}
-      {% if swarm_placement_mode == 'replicated' %}
-      replicas: {{ swarm_replicas }}
-      {% endif %}
-      {% if traefik_enabled %}
-      labels:
-        - traefik.enable=true
-        - 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 }}`)
-        - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}
-      {% endif %}
-    {% else %}
-    {% if traefik_enabled %}
-    labels:
-      - traefik.enable=true
-      - 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 }}`)
-      - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}
-    {% endif %}
-    restart: {{ restart_policy }}
-    {% endif %}
-    {% if not traefik_enabled %}
-    ports:
-      {% if swarm_enabled %}
-      # Swarm mode: long syntax with mode: host
-      - target: {{ test_port }}
-        published: {{ ports_http }}
-        protocol: tcp
-        mode: host
-      - target: 443
-        published: {{ ports_https }}
-        protocol: tcp
-        mode: host
-      {% else %}
-      # Standalone mode: short syntax
-      - "{{ ports_http }}:{{ test_port }}"
-      - "{{ ports_https }}:443"
-      {% endif %}
-    {% endif %}
-    networks:
-      {% if traefik_enabled %}
-      - {{ traefik_network }}
-      {% endif %}
-      - {{ network_name }}
-
-networks:
-  {% if traefik_enabled %}
-  {{ traefik_network }}:
-    external: true
-  {% endif %}
-  {{ network_name }}:
-    {% if swarm_enabled %}
-    driver: overlay
-    attachable: true
-    {% else %}
-    driver: bridge
-    {% endif %}

archetypes/compose/secrets-v1.j2

@@ -0,0 +1,20 @@
+{#
+  Archetype: toplevel-secrets-v1
+  
+  Description:
+    Swarm secrets definition from file source.
+  
+  Approach:
+    - Only applies to swarm mode
+    - Reads secret from file at deploy time
+    - Secrets are encrypted in swarm
+  
+  Usage:
+    Use with service-secrets-v1 for secure credential management.
+    Create .env.secret file containing the secret value.
+#}
+{% if swarm_enabled %}
+secrets:
+  {{ secret_name }}:
+    file: ./.env.secret
+{% endif %}

archetypes/compose/service-configs-v1.j2

@@ -0,0 +1,20 @@
+{#
+  Archetype: service-configs-v1
+  
+  Description:
+    Swarm configs reference for configuration files.
+  
+  Approach:
+    - Only applies to swarm mode
+    - References configs defined in top-level configs section
+    - Configs mounted at specified target path
+  
+  Usage:
+    Use for application configuration files in swarm.
+    Requires corresponding toplevel-configs-v1 archetype.
+#}
+    {% if swarm_enabled %}
+    configs:
+      - source: {{ config_name }}
+        target: /etc/app/config.yaml
+    {% endif %}

archetypes/compose/service-deploy-v1.j2

@@ -0,0 +1,38 @@
+{#
+  Archetype: service-deploy-traefik-v1
+  
+  Description:
+    Swarm deployment with Traefik labels in deploy section.
+  
+  Approach:
+    - Labels must be in deploy section for swarm mode
+    - Includes full HTTP + HTTPS Traefik configuration
+    - Critical: traefik.docker.network label for multi-network containers
+  
+  Usage:
+    Use for swarm services exposed through Traefik.
+    Combines with service-labels-traefik-https-v1 for standalone mode.
+#}
+    {% if swarm_enabled and traefik_enabled %}
+    deploy:
+      mode: {{ swarm_placement_mode }}
+      {% if swarm_placement_mode == 'replicated' %}
+      replicas: {{ swarm_replicas }}
+      {% endif %}
+      restart_policy:
+        condition: on-failure
+      labels:
+        - traefik.enable=true
+        - traefik.docker.network={{ traefik_network }}
+        - traefik.http.services.{{ service_name }}-web.loadBalancer.server.port={{ service_port }}
+        - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}-web
+        - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
+        - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}
+        {% if traefik_tls_enabled %}
+        - traefik.http.routers.{{ service_name }}-https.service={{ service_name }}-web
+        - traefik.http.routers.{{ service_name }}-https.rule=Host(`{{ traefik_host }}`)
+        - traefik.http.routers.{{ service_name }}-https.entrypoints={{ traefik_tls_entrypoint }}
+        - traefik.http.routers.{{ service_name }}-https.tls=true
+        - traefik.http.routers.{{ service_name }}-https.tls.certresolver={{ traefik_tls_certresolver }}
+        {% endif %}
+    {% endif %}

archetypes/compose/service-envfile-v1.j2

@@ -0,0 +1,17 @@
+{#
+  Archetype: service-environment-file-v1
+  
+  Description:
+    References external environment file(s) for configuration.
+  
+  Approach:
+    - Loads variables from .env file(s)
+    - Keeps sensitive data out of compose file
+    - Supports multiple env files
+  
+  Usage:
+    Use for services with many environment variables or sensitive data.
+    Create corresponding .env.j2 template file.
+#}
+    env_file:
+      - .env.{{ service_name }}

archetypes/compose/service-environment-v1.j2

@@ -0,0 +1,21 @@
+{#
+  Archetype: service-environment-v1
+  
+  Description:
+    Sets environment variables directly in the compose file.
+  
+  Approach:
+    - Always includes TZ (timezone) variable
+    - Swarm-compatible (env_file doesn't work in Swarm mode)
+    - Can be extended with additional environment variables
+  
+  Usage:
+    Use for services that need environment variables set directly.
+    This approach works in both standard Docker Compose and Swarm mode.
+    
+  Notes:
+    - For sensitive data in Swarm mode, use secrets instead
+    - For many variables in standard mode, consider env_file archetype
+#}
+    environment:
+      - TZ={{ container_timezone }}

archetypes/compose/traefik-v1.j2 → archetypes/compose/service-labels-v1.j2

@@ -1,29 +1,33 @@
----
-services:
-  {{ service_name }}:
-    image: {{ test_image }}
+{#
+  Archetype: service-labels-traefik-middleware-v1
+  
+  Description:
+    Traefik labels with middleware support for authentication, headers, etc.
+  
+  Approach:
+    - Extends HTTPS configuration with middleware assignment
+    - Middlewares applied to both HTTP and HTTPS routers
+    - Supports chaining multiple middlewares (comma-separated)
+  
+  Usage:
+    Use when you need authentication, rate limiting, headers, or other
+    Traefik middleware features. Define middlewares in Traefik config or labels.
+#}
     {% 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.services.{{ service_name }}-web.loadBalancer.server.port={{ service_port }}
       - traefik.http.routers.{{ service_name }}-http.service={{ service_name }}-web
       - traefik.http.routers.{{ service_name }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}
+      - traefik.http.routers.{{ service_name }}-http.middlewares={{ traefik_middleware }}
       {% if traefik_tls_enabled %}
       - traefik.http.routers.{{ service_name }}-https.service={{ service_name }}-web
       - traefik.http.routers.{{ service_name }}-https.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name }}-https.entrypoints={{ traefik_tls_entrypoint }}
       - traefik.http.routers.{{ service_name }}-https.tls=true
       - traefik.http.routers.{{ service_name }}-https.tls.certresolver={{ traefik_tls_certresolver }}
+      - traefik.http.routers.{{ service_name }}-https.middlewares={{ traefik_middleware }}
       {% endif %}
-    networks:
-      - {{ traefik_network }}
     {% endif %}
-    restart: {{ restart_policy }}
-
-{% if traefik_enabled %}
-networks:
-  {{ traefik_network }}:
-    external: true
-{% endif %}

archetypes/compose/service-networks-v1.j2

@@ -0,0 +1,30 @@
+{#
+  Archetype: service-networks-macvlan-v1
+  
+  Description:
+    Network configuration supporting host, bridge, and macvlan modes.
+  
+  Approach:
+    - Host mode: Uses network_mode: host (no networks section)
+    - Macvlan mode: Assigns static IP address
+    - Bridge mode: Simple network attachment
+    - Always includes Traefik network if enabled
+  
+  Usage:
+    Use for services that need specific network modes (e.g., Pi-hole with macvlan).
+    Requires network_mode variable ('host', 'bridge', or 'macvlan').
+#}
+    {% if network_mode == 'host' %}
+    network_mode: host
+    {% else %}
+    networks:
+      {% if traefik_enabled %}
+      {{ traefik_network }}:
+      {% endif %}
+      {% if network_mode == 'macvlan' %}
+      {{ network_name }}:
+        ipv4_address: {{ network_macvlan_ipv4_address }}
+      {% elif network_mode == 'bridge' %}
+      {{ network_name }}:
+      {% endif %}
+    {% endif %}

archetypes/compose/service-ports-v1.j2

@@ -0,0 +1,28 @@
+{#
+  Archetype: service-ports-conditional-v1
+  
+  Description:
+    Port mappings that are only exposed when Traefik is disabled.
+  
+  Approach:
+    - Swarm mode: Uses long syntax with mode:host for proper host binding
+    - Standalone mode: Uses short syntax for simplicity
+    - Conditionally skipped if Traefik handles routing
+  
+  Usage:
+    Use for HTTP/HTTPS services that can be proxied through Traefik.
+    Ports are only exposed directly when traefik_enabled=false.
+#}
+    {% if not traefik_enabled %}
+    ports:
+      {% if swarm_enabled %}
+      # Swarm: long syntax with mode host
+      - target: {{ service_port }}
+        published: {{ ports_http }}
+        protocol: tcp
+        mode: host
+      {% else %}
+      # Standalone: short syntax
+      - "{{ ports_http }}:{{ service_port }}"
+      {% endif %}
+    {% endif %}

archetypes/compose/service-secrets-v1.j2

@@ -0,0 +1,20 @@
+{#
+  Archetype: service-secrets-v1
+  
+  Description:
+    Swarm secrets reference for sensitive data.
+  
+  Approach:
+    - Only applies to swarm mode
+    - References secrets defined in top-level secrets section
+    - Secrets mounted at /run/secrets/<secret_name>
+  
+  Usage:
+    Use for passwords, API keys, certificates in swarm.
+    Requires corresponding secrets-v1 (top-level) archetype.
+    Must be used within a service definition.
+#}
+{% if swarm_enabled %}
+    secrets:
+      - {{ secret_name }}
+{% endif %}

archetypes/compose/service-v1.j2

@@ -0,0 +1,23 @@
+{#
+  Archetype: service-basic-v1
+  
+  Description:
+    Basic service definition with image, container name (non-swarm), and hostname.
+    This is the foundation for any Docker Compose service.
+  
+  Approach:
+    - Defines the service name and image
+    - Conditionally adds container_name only for non-swarm deployments
+    - Sets hostname for service identification
+  
+  Usage:
+    Use this as the starting point for any service definition.
+#}
+services:
+  {{ service_name }}:
+    image: {{ service_image }}
+    {% if not swarm_enabled %}
+    restart: {{ restart_policy }}
+    container_name: {{ container_name }}
+    {% endif %}
+    hostname: {{ container_hostname }}

archetypes/compose/service-volumes-v1.j2

@@ -0,0 +1,25 @@
+{#
+  Archetype: service-volumes-swarm-v1
+  
+  Description:
+    Swarm-aware volume mounts supporting mount/local/NFS modes.
+  
+  Approach:
+    - Swarm mount mode: Uses host path for bind mounts
+    - Swarm local/NFS mode: Uses named volumes
+    - Standalone mode: Always uses named volumes
+  
+  Usage:
+    Use for swarm deployments where you need flexibility in volume storage.
+    Requires swarm_volume_mode and swarm_volume_mount_path variables.
+#}
+    volumes:
+      {% if swarm_enabled %}
+        {% if swarm_volume_mode == 'mount' %}
+      - {{ swarm_volume_mount_path }}/data:/data:rw
+        {% elif swarm_volume_mode in ['local', 'nfs'] %}
+      - app_data:/data
+        {% endif %}
+      {% else %}
+      - app_data:/data
+      {% endif %}

archetypes/compose/swarm-v1.j2

@@ -1,79 +0,0 @@
----
-services:
-  {{ service_name }}:
-    image: {{ test_image }}
-    {% if swarm_enabled %}
-    deploy:
-      mode: {{ swarm_placement_mode }}
-      {% if swarm_placement_mode == 'replicated' %}
-      replicas: {{ swarm_replicas }}
-      {% endif %}
-      {% if swarm_placement_host %}
-      placement:
-        constraints:
-          - node.hostname == {{ swarm_placement_host }}
-      {% endif %}
-      {% 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 }}`)
-        - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}
-        {% if traefik_tls_enabled %}
-        - traefik.http.routers.{{ service_name }}-https.service={{ service_name }}-web
-        - traefik.http.routers.{{ service_name }}-https.rule=Host(`{{ traefik_host }}`)
-        - traefik.http.routers.{{ service_name }}-https.entrypoints={{ traefik_tls_entrypoint }}
-        - traefik.http.routers.{{ service_name }}-https.tls=true
-        - traefik.http.routers.{{ service_name }}-https.tls.certresolver={{ traefik_tls_certresolver }}
-        {% endif %}
-      {% endif %}
-      update_config:
-        parallelism: 1
-        delay: 10s
-      restart_policy:
-        condition: on-failure
-    {% else %}
-    {% 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 }}`)
-      - traefik.http.routers.{{ service_name }}-http.entrypoints={{ traefik_entrypoint }}
-      {% if traefik_tls_enabled %}
-      - traefik.http.routers.{{ service_name }}-https.service={{ service_name }}-web
-      - traefik.http.routers.{{ service_name }}-https.rule=Host(`{{ traefik_host }}`)
-      - traefik.http.routers.{{ service_name }}-https.entrypoints={{ traefik_tls_entrypoint }}
-      - traefik.http.routers.{{ service_name }}-https.tls=true
-      - traefik.http.routers.{{ service_name }}-https.tls.certresolver={{ traefik_tls_certresolver }}
-      {% endif %}
-    {% endif %}
-    restart: {{ restart_policy }}
-    {% endif %}
-    networks:
-      {% if traefik_enabled %}
-      - {{ traefik_network }}
-      {% endif %}
-      - {{ network_name }}
-
-{% if swarm_enabled %}
-networks:
-  {% if traefik_enabled %}
-  {{ traefik_network }}:
-    external: true
-  {% endif %}
-  {{ network_name }}:
-    driver: overlay
-    attachable: true
-{% else %}
-networks:
-  {% if traefik_enabled %}
-  {{ traefik_network }}:
-    external: true
-  {% endif %}
-  {{ network_name }}:
-    driver: bridge
-{% endif %}

archetypes/compose/volumes-v1.j2

@@ -0,0 +1,40 @@
+{#
+  Archetype: volumes-v1
+  
+  Description:
+    Consolidated top-level volumes section supporting multiple modes:
+    - Simple: Basic local volumes for standalone deployments
+    - External: Reference pre-existing volumes
+    - NFS: Network filesystem for shared storage in swarm
+    - Swarm: Flexible mode supporting mount/local/NFS strategies
+  
+  Approach:
+    - External volumes: No definition needed (external: true not used at top-level)
+    - Standalone mode: Always uses local volumes
+    - Swarm mode with mount: No volume definition (uses bind mounts)
+    - Swarm mode with local: Simple local volumes
+    - Swarm mode with NFS: Network filesystem with driver options
+  
+  Usage:
+    Use as the single volumes archetype for all deployment types.
+    Adapts based on volume_external, swarm_enabled, and swarm_volume_mode variables.
+#}
+{% if not volume_external %}
+{% if swarm_enabled %}
+{% if swarm_volume_mode in ['local', 'nfs'] %}
+volumes:
+  {{ volume_name }}:
+    {% if swarm_volume_mode == 'nfs' %}
+    driver: local
+    driver_opts:
+      type: nfs
+      o: addr={{ swarm_volume_nfs_server }},{{ swarm_volume_nfs_options }}
+      device: ":{{ swarm_volume_nfs_path }}"
+    {% endif %}
+{% endif %}
+{% else %}
+volumes:
+  {{ volume_name }}:
+    driver: local
+{% endif %}
+{% endif %}