2025-11-12 pihole6 - master branch - PR 1 of 2

Adds Pi-hole version 6 as variant to avoid backwards compatibility
problems with Pi-hole version 5.

The primary issue was adapting the four standard environment variables
from version 5 to version 6 requirements. The defaults for version 6
are unchanged from version 5.

Documentation added to master branch. Also took the opportunity to
extend and clarify certain aspects of Pi-hole usage, such as local
upstream resolvers.

Pi-hole v5 documentation adjusted to alert readers to presence of
version 6.

Signed-off-by: Phill Kelley <[email protected]>

Author: Paraphraser

.templates/pihole6/service.yml

@@ -0,0 +1,28 @@
+pihole6:
+  # see https://sensorsiot.github.io/IOTstack/Containers/Pi-hole/
+  container_name: pihole6
+  image: pihole/pihole:latest
+  restart: unless-stopped
+  x-network_mode: host
+  ports:
+    - "8089:80/tcp"
+    - "53:53/tcp"
+    - "53:53/udp"
+    - "67:67/udp"
+  # - "4443:443/tcp"
+  environment:
+    # see https://docs.pi-hole.net/docker/configuration/
+    TZ: ${TZ:-Etc/UTC}
+    FTLCONF_webserver_api_password: '${PIHOLE_ADMIN_PASSWORD:-}'
+    FTLCONF_dns_interface: eth0
+    FTLCONF_database_maxDBdays: 365
+    FTLCONF_dns_upstreams: 8.8.8.8;8.8.4.4
+  volumes:
+    - ./volumes/pihole6/etc-pihole:/etc/pihole
+    - ./volumes/pihole6/etc-dnsmasq.d:/etc/dnsmasq.d
+  dns:
+    - 127.0.0.1
+    - 1.1.1.1
+  cap_add:
+    - NET_ADMIN
+

docs/Containers/Pi-hole.md

@@ -1,7 +1,29 @@
-# Pi-hole
+# Pi-hole version 5
 
 Pi-hole is a fantastic utility to reduce ads.
 
+## Pi-hole variants { #variants }
+
+In early 2025, Pi-hole underwent some major changes which broke compatibility with previous versions. In particular, the naming scheme for environment variables changed drastically. For IOTstack users, the immediate result of "pulling" the `latest` image from DockerHub was silent behavioural changes by the container.
+
+IOTstack reacted to this problem by pinning to version 2024.07.0. This was to "hold the ring" pending a solution. The solution is that the IOTstack menu now supports two variants:
+
+* **Pi-hole 5**
+
+	The IOTstack menu refers to this as `pihole`. It is pinned to version [2024.07.0](https://github.com/pi-hole/docker-pi-hole/releases/tag/2024.07.0) which is the final release of version 5. This document describes version 5.
+
+* **Pi-hole 6**
+
+	The IOTstack menu refers to this as `pihole6`. That variant tracks DockerHub images with the `latest` tag so it will keep updating as later versions are released. See [Pi-hole version 6](./Pi-hole6.md).
+
+If you are installing Pi-hole for the first time, you should choose `pihole6` from the menu.
+
+See [migration](#migration) if you are currently running Pi-hole 5 and want to upgrade to Pi-hole 6.
+
+Note:
+
+* You can't run both versions at the same time. That is because they both claim the same network ports.
+
 ## References { #references }
 
 * [Pi-hole on GitHub](https://github.com/pi-hole/docker-pi-hole)