ChristianLempa_Boilerplates/library/compose/pihole/template.yaml

---
kind: compose
schema: "1.1"
metadata:
  name: Pihole
  description: >
    Network-wide advertisement and internet tracker blocking application that functions as a DNS blackhole.
    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/

    Documentation: https://docs.pi-hole.net/

    GitHub: https://github.com/pi-hole/pi-hole
  version: 2025.08.0
  author: Christian Lempa
  date: '2025-09-28'
  tags:
    - dns
    - ad-blocking
  draft: false
  next_steps: |
    {% if swarm_enabled -%}
    1. Create Docker Swarm secret for admin password:
       echo "{{ webpassword }}" | docker secret create {{ webpassword_secret_name }} -
       (Or use the generated .env.secret file)

    2. Deploy to Swarm:
       docker stack deploy -c compose.yaml pihole

    3. Verify deployment:
       docker service ls
       docker service logs pihole_{{ service_name }}

    4. Access web interface:
       {% if network_mode == 'macvlan' -%}https://{{ network_macvlan_ipv4_address }}/admin/login
       {%- elif traefik_enabled == True -%}https://{{ traefik_host }}/admin/login
       {%- else -%}https://localhost:{{ ports_https }}/admin/login{%- endif %}

    5. Login password: Stored in Docker secret '{{ webpassword_secret_name }}'

    6. Configure devices to use your swarm node's IP address as DNS server
    {% else -%}
    1. Start: docker compose up -d

    2. Access web interface:
       {% if network_mode == 'macvlan' -%}https://{{ network_macvlan_ipv4_address }}/admin/login
       {%- elif traefik_enabled == True -%}https://{{ traefik_host }}/admin/login
       {%- else -%}https://localhost:{{ ports_https }}/admin/login{%- endif %}

    3. Login password: {{ webpassword }}

    4. Configure devices to use your host's IP address as DNS server
    {% endif -%}
spec:
  general:
    vars:
      service_name:
        default: "pihole"
      container_name:
        default: "pihole"
  admin_settings:
    description: "Admin Pi-hole Settings"
    required: true
    vars:
      webpassword:
        description: "Web interface admin password"
        type: str
        sensitive: true
        default: ""
        autogenerated: true
  traefik:
    vars:
      traefik_host:
        default: "pihole.home.arpa"
  network:
    vars:
      network_mode:
        extra: "If you need DHCP functionality, use 'host' or 'macvlan' mode"
      network_name:
        default: "pihole_network"
  ports:
    needs: "network_mode=bridge"
    vars:
      ports_https:
        description: "External HTTPS port"
        type: int
        default: 8443
        extra: "Only used if Traefik is not enabled"
      ports_dns:
        description: "External DNS port"
        type: int
        default: 53
      ports_ntp:
        description: "External NTP port"
        type: int
        default: 123
  swarm:
    vars:
      swarm_placement_host:
        required: true
      webpassword_secret_name:
        description: "Docker Swarm secret name for admin password"
        type: str
        default: "pihole_webpassword"