ChristianLempa_Boilerplates/library/compose/pihole/template.yaml

---
kind: compose
metadata:
  icon:
    provider: selfh
    id: pi-hole
  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.
    ## Prerequisites
    - :warning: Pi-hole uses local storage and configuration files and does NOT support running multiple replicas.
    This template enforces a single replica with node placement constraints to ensure stable DNS resolution.
    ## References
    - **Project:** https://pi-hole.net/
    - **Documentation:** https://docs.pi-hole.net/
    - **GitHub:** https://github.com/pi-hole/pi-hole
  version: 2025.11.1
  author: Christian Lempa
  date: '2025-12-11'
  tags:
    - traefik
    - swarm
    - network
    - volume
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: secret
        config:
          autogenerated: true
  ports:
    vars:
      ports_http:
        description: HTTP port for Pi-hole
        type: int
        default: 80
      ports_https:
        description: HTTPS port for Pi-hole
        type: int
        default: 443
      ports_ntp:
        description: "External NTP port"
        type: int
        default: 123
        required: true
  traefik:
    vars:
      traefik_host:
        default: pihole
  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"
  swarm:
    vars:
      swarm_placement_host:
        required: true
        optional: false
        needs: null
      swarm_replicas:
        description: Number of replicas for Swarm mode
        type: int
        default: 1