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 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/

    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: |
    1. Start: docker compose up -d

    2. Access web interface:
       {% if network_enabled and network_mode == 'macvlan' -%}
       http://{{ network_macvlan_ipv4_address }}
       {% elif traefik_enabled -%}
       {% if traefik_tls_enabled %}https{% else %}http{% endif %}://{{ traefik_host }}
       {%- elif ports_enabled -%}
       http://localhost:{{ ports_http }}/admin/login
       {%- endif %}

    3. Login password: {{ pihole_webpassword }}
       (stored in .env.pihole file)

    {% if network_enabled and network_mode == 'macvlan' -%}
    4. Configure devices to use {{ network_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:
  general:
    vars:
      service_name:
        default: "pihole"
      container_name:
        default: "pihole"
  pihole:
    required: true
    vars:
      pihole_webpassword:
        description: "Web interface admin password"
        type: str
        sensitive: true
        default: ""
        autogenerated: true
      pihole_dns_upstreams:
        description: "Upstream DNS servers"
        type: str
        default: "1.1.1.1;1.0.0.1"
        extra: "Separate multiple DNS servers with semicolons (;)"
      dns_enabled:
        type: bool
        description: "Enable DNS server functionality"
        default: true
        extra: "Exposes port 53 for DNS queries in bridge network mode"
      dhcp_enabled:
        type: bool
        needs: "network_mode=host,macvlan"
        description: "Enable DHCP server functionality (requires host or macvlan network mode)"
        default: true
  traefik:
    vars:
      traefik_host:
        default: "pihole.home.arpa"
  network:
    required: true
    vars:
      network_name:
        default: "pihole_network"
      network_external:
        default: false
  ports:
    needs: "network_mode=bridge"
    vars:
      ports_https:
        description: "HTTPS port for web interface"
        type: int
        default: 8443
        extra: "Only used if Traefik is not enabled"