feature(compose): enhance pihole template with macvlan and improved traefik integration

library/compose/pihole/compose.yaml.j2

@@ -2,36 +2,46 @@ services:
   {{ service_name | default('pihole') }}:
     container_name: {{ container_name | default('pihole') }}
     image: docker.io/pihole/pihole:2025.08.0
-    {% if ports_enabled %}
+    {% if traefik_enabled or macvlan_enabled %}
+    networks:
+      {% if traefik_enabled %}
+      {{ traefik_network | default('traefik') }}:
+      {% endif %}
+      {% if macvlan_enabled %}
+      pihole_macvlan:
+        ipv4_address: {{ macvlan_ipv4_address }}
+      {% endif %}
+    {% endif %}
+    {% if ports_enabled and not macvlan_enabled and (not traefik_enabled or dns_enabled or dhcp_enabled) %}
     ports:
-      - "{{ ports_dns_tcp | default(53) }}:53/tcp"
-      - "{{ ports_dns_udp | default(53) }}:53/udp"
-      - "{{ ports_dhcp | default(67) }}:67/udp"
-      - "{{ ports_http | default(8081) }}:80/tcp"
-      - "{{ ports_https | default(8443) }}:443/tcp"
+      {% if not traefik_enabled %}
+      - "{{ ports_http }}:80/tcp"
+      - "{{ ports_https }}:443/tcp"
+      {% endif %}
+      {% if dns_enabled %}
+      - "53:53/tcp"
+      - "53:53/udp"
+      {% endif %}
+      {% if dhcp_enabled %}
+      - "67:67/udp"
+      {% endif %}
     {% endif %}
     environment:
       - TZ={{ container_timezone | default('UTC') }}
-      {% if pihole_webpassword %}
-      - FTLCONF_webserver_api_password={{ pihole_webpassword }}
-      {% endif %}
-      - FTLCONF_dns_upstreams={{ pihole_dns_upstreams | default('8.8.8.8;8.8.4.4') }}
+      {% if pihole_webpassword %}      - FTLCONF_webserver_api_password={{ pihole_webpassword }}
+      {% endif %}      - FTLCONF_dns_upstreams={{ pihole_dns_upstreams | default('1.1.1.1;1.0.0.1') }}
     volumes:
       - config_dnsmasq:/etc/dnsmasq.d
       - config_pihole:/etc/pihole
-    {% if network_enabled %}
-    networks:
-      - {{ network_name | default('bridge') }}
-    {% endif %}
     {% if traefik_enabled %}
     labels:
       - traefik.enable=true
-      - traefik.http.services.{{ service_name | default('pihole') }}.loadBalancer.server.port=80
-      - traefik.http.routers.{{ service_name | default('pihole') }}-http.service={{ service_name | default('pihole') }}
+      - traefik.http.services.{{ service_name | default('pihole') }}-web.loadBalancer.server.port=80
+      - traefik.http.routers.{{ service_name | default('pihole') }}-http.service={{ service_name | default('pihole') }}-web
       - traefik.http.routers.{{ service_name | default('pihole') }}-http.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name | default('pihole') }}-http.entrypoints={{ traefik_entrypoint | default('web') }}
       {% if traefik_tls_enabled %}
-      - traefik.http.routers.{{ service_name | default('pihole') }}-https.service={{ service_name | default('pihole') }}
+      - traefik.http.routers.{{ service_name | default('pihole') }}-https.service={{ service_name | default('pihole') }}-web
       - traefik.http.routers.{{ service_name | default('pihole') }}-https.rule=Host(`{{ traefik_host }}`)
       - traefik.http.routers.{{ service_name | default('pihole') }}-https.entrypoints={{ traefik_tls_entrypoint | default('websecure') }}
       - traefik.http.routers.{{ service_name | default('pihole') }}-https.tls=true
@@ -46,10 +56,20 @@ volumes:
   config_pihole:
     driver: local
 
-{% if network_enabled %}
+{% if traefik_enabled or macvlan_enabled %}
 networks:
-  {{ network_name | default('bridge') }}:
-    {% if network_external %}
+  {% if macvlan_enabled %}
+  pihole_macvlan:
+    driver: macvlan
+    driver_opts:
+      parent: {{ macvlan_parent_interface }}
+    ipam:
+      config:
+        - subnet: {{ macvlan_subnet }}
+          gateway: {{ macvlan_gateway }}
+  {% endif %}
+  {% if traefik_enabled %}
+  {{ traefik_network | default('traefik') }}:
     external: true
-    {% endif %}
+  {% endif %}
 {% endif %}

library/compose/pihole/template.yaml

@@ -3,9 +3,9 @@ kind: compose
 metadata:
   name: Pihole
   description: >
-    Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, blocking ads and trackers for all devices on your network.
-    It improves browsing speed, enhances privacy, and reduces bandwidth usage by filtering out unwanted content at the DNS level.
-    Pi-hole can be easily integrated with existing routers and supports custom blocklists and whitelists.
+    Network-wide advertisement and internet tracker blocking application that functions as a DNS sinkhole.
+    Provides DNS-level content filtering for all network devices, improving browsing performance, privacy, and security.
+    Supports custom blocklists, whitelists, and seamless integration with existing network infrastructure.
 
 
     Project: https://pi-hole.net/
@@ -19,46 +19,82 @@ metadata:
   tags:
     - dns
     - ad-blocking
-  draft: true
+  draft: false
+  next_steps: |
+    1. Start: docker compose up -d
+
+    2. Access web interface:
+       {% if macvlan_enabled -%}
+       http://{{ macvlan_ipv4_address }}
+       {% elif traefik_enabled -%}
+       {% if traefik_tls_enabled %}https{% else %}http{% endif %}://{{ traefik_host }}
+       {%- elif ports_enabled -%}
+       http://localhost:{{ ports_http }}
+       {%- endif %}
+
+    3. Login password: {{ pihole_webpassword }}
+
+    {% if macvlan_enabled -%}
+    4. Configure devices to use {{ macvlan_ipv4_address }} as DNS server
+       {% if dhcp_enabled %}Configure DHCP in Settings > DHCP{% endif %}
+    {%- elif ports_enabled and dns_enabled -%}
+    4. Configure devices to use Docker host IP as DNS server (port 53)
+       {% if dhcp_enabled %}Configure DHCP in Settings > DHCP (port 67){% endif %}
+    {%- endif %}
 spec:
-  ports:
-    vars:
-      ports_http:
-        description: "Host port for HTTP web interface (80)"
-        type: int
-        default: 8080
-      ports_https:
-        description: "Host port for HTTPS web interface (443)"
-        type: int
-        default: 8443
-      ports_dns_udp:
-        description: "Host port for DNS over UDP (53)"
-        type: int
-        default: 53
-      ports_dns_tcp:
-        description: "Host port for DNS over TCP (53)"
-        type: int
-        default: 53
-      ports_dhcp:
-        description: "Host port for DHCP (67)"
-        type: int
-        default: 67
   pihole:
-    description: "Pi-hole configuration settings"
     required: true
     vars:
       pihole_webpassword:
         description: "Web interface admin password"
         type: str
         sensitive: true
-        default: "changeme"
+        default: ""
+        autogenerated: true
       pihole_dns_upstreams:
         description: "Upstream DNS servers (semicolon separated)"
         type: str
         default: "1.1.1.1;1.0.0.1"
-  general:
+      dns_enabled:
+        type: bool
+        description: "Enable DNS server functionality"
+        default: false
+      dhcp_enabled:
+        type: bool
+        description: "Enable DHCP server functionality"
+        default: false
+  traefik:
+    vars:
+      traefik_host:
+        default: "pihole.home.arpa"
+  macvlan:
+    toggle: macvlan_enabled
     vars:
-      pihole_version:
+      macvlan_enabled:
+        type: bool
+        description: "Enable macvlan network mode"
+        default: false
+      macvlan_ipv4_address:
+        type: str
+        description: "Static IP address for Pi-hole"
+        default: "192.168.1.253"
+      macvlan_parent_interface:
+        type: str
+        description: "Host network interface name"
+        default: "eth0"
+      macvlan_subnet:
         type: str
-        description: Pihole version
-        default: latest
+        description: "Network subnet in CIDR notation"
+        default: "192.168.1.0/24"
+      macvlan_gateway:
+        type: str
+        description: "Network gateway IP address"
+        default: "192.168.1.1"
+  ports:
+    vars:
+      ports_http:
+        type: int
+        default: 8080
+      ports_https:
+        type: int
+        default: 8443