---
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.10.2
  author: Christian Lempa
  date: '2025-10-28'
  tags:
    - dns
    - ad-blocking
  next_steps: |
    {% if swarm_enabled -%}
    1. Deploy to Docker Swarm:
       docker stack deploy -c compose.yaml pihole
    2. Access the Web Interface:
       {%- if traefik_enabled == True -%}https://{{ traefik_host }}/admin
       {%- else -%}https://<your-swarm-node-ip>:{{ ports_https }}/admin{%- endif %}
    3. Configure devices to use swarm node IP as DNS
    {% else -%}
    1. Deploy to Docker:
       docker compose up -d
    2. Access the Web Interface:
       {%- if traefik_enabled == True -%}https://{{ traefik_host }}/admin
       {%- else -%}https://<your-docker-host-ip>:{{ ports_https }}/admin{%- endif %}
    3. Configure devices to use docker host IP as DNS
    {% 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_enabled:
        needs: "network_mode=bridge"
      traefik_host:
        default: "pihole.home.arpa"
  network:
    vars:
      network_mode:
        extra: >
          If you need DHCP functionality, use 'host' or 'macvlan' mode.
          NOTE: Swarm only supports 'bridge' mode!"
      network_name:
        default: "pihole_network"
  ports:
    vars:
      ports_http:
        description: "External HTTP port"
        type: int
        default: 8080
        needs: ["traefik_enabled=false", "network_mode=bridge"]
      ports_https:
        description: "External HTTPS port"
        type: int
        default: 8443
        needs: ["traefik_enabled=false", "network_mode=bridge"]
      ports_dns:
        description: "External DNS port"
        type: int
        default: 53
        needs: "network_mode=bridge"
      ports_ntp:
        description: "External NTP port"
        type: int
        default: 123
        needs: "network_mode=bridge"
  swarm:
    vars:
      swarm_enabled:
        needs: "network_mode=bridge"
      swarm_placement_host:
        required: true
        optional: false
        needs: null
      webpassword_secret_name:
        description: "Docker Swarm secret name for admin password"
        type: str
        default: "pihole_webpassword"