---
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
  next_steps: 'Log in with your initial admin user:

    ```bash

    Username: admin

    Password: {{ webpassword }}

    ```'
schema: '1.2'
spec:
  general:
    vars:
      service_name:
        default: pihole
      container_name:
        default: pihole
      container_hostname:
        type: str
      container_timezone:
        type: str
      user_uid:
        type: int
        default: 1000
      user_gid:
        type: int
        default: 1000
      restart_policy:
        type: enum
        options:
          - unless-stopped
          - always
          - on-failure
          - 'no'
        default: unless-stopped
        required: true
  admin_settings:
    description: Admin Pi-hole Settings
    required: true
    vars:
      webpassword:
        description: Web interface admin password
        type: str
        sensitive: true
        autogenerated: true
  ports:
    vars:
      ports_dns:
        description: DNS port for Pi-hole
        type: int
        default: 53
        required: true
      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
      traefik_network:
        default: traefik
        type: str
        required: true
      traefik_domain:
        default: home.arpa
        type: str
        required: true
      traefik_enabled:
        type: bool
        default: false
        description: Enable Traefik integration
  traefik_tls:
    vars:
      traefik_tls_certresolver:
        type: str
        default: cloudflare
        required: true
      traefik_tls_enabled:
        type: bool
        default: false
        description: Enable Traefik TLS
  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
      network_macvlan_ipv4_address:
        type: str
        default: 192.168.1.253
        needs:
          - network_mode=macvlan
        required: true
      network_macvlan_parent_interface:
        type: str
        default: eth0
        needs:
          - network_mode=macvlan
        required: true
      network_macvlan_subnet:
        type: str
        default: 192.168.1.0/24
        needs:
          - network_mode=macvlan
        required: true
      network_macvlan_gateway:
        type: str
        default: 192.168.1.1
        needs:
          - network_mode=macvlan
        required: true
      network_external:
        type: bool
        default: false
        description: Whether the network is external
  swarm:
    vars:
      swarm_placement_host:
        required: true
        optional: false
        needs: null
      swarm_replicas:
        description: Number of replicas for Swarm mode
        type: int
        default: 1
      swarm_enabled:
        type: bool
        default: false
        description: Enable Docker Swarm mode
      swarm_placement_mode:
        type: str
        default: replicated
        description: The placement mode
  volume:
    vars:
      volume_mode:
        type: enum
        options:
          - local
          - mount
          - nfs
        default: local
        required: true
      volume_mount_path:
        type: str
        default: /mnt/storage
        needs:
          - volume_mode=mount
        required: true
      volume_nfs_server:
        type: str
        default: 192.168.1.1
        needs:
          - volume_mode=nfs
        required: true
      volume_nfs_path:
        type: str
        default: /export
        needs:
          - volume_mode=nfs
        required: true
      volume_nfs_options:
        type: str
        default: rw,nolock,soft
        needs:
          - volume_mode=nfs
        required: true