1 files changed, 89 insertions, 0 deletions
diff --git a/unsorted/docker_compose_stacks/pihole/README.md b/unsorted/docker_compose_stacks/pihole/README.md
new file mode 100644
index 0000000..e19a1a8
--- /dev/null
+++ b/unsorted/docker_compose_stacks/pihole/README.md
@@ -0,0 +1,89 @@
+# Pi-hole Docker Stack
+
+A Docker Compose configuration for running [Pi-hole](https://pi-hole.net/), a network-wide ad blocker that acts as a DNS sinkhole.
+
+## Features
+
+- DNS-based ad blocking for your entire network
+- Web-based admin interface
+- DHCP server capability
+- NTP server for time synchronization
+
+## Exposed Ports
+
+| Port | Protocol | Service               |
+| ---- | -------- | --------------------- |
+| 53   | TCP/UDP  | DNS                   |
+| 80   | TCP      | HTTP (Web Interface)  |
+| 443  | TCP      | HTTPS (Web Interface) |
+| 67   | UDP      | DHCP                  |
+| 123  | UDP      | NTP                   |
+
+## Configuration
+
+### Environment Variables
+
+| Variable                         | Description                  | Default         |
+| -------------------------------- | ---------------------------- | --------------- |
+| `TZ`                             | Timezone                     | `Europe/London` |
+| `FTLCONF_webserver_api_password` | Admin web interface password | `CHANGEME`      |
+| `FTLCONF_dns_listeningMode`      | DNS listening mode           | `ALL`           |
+
+> ⚠️ **Important:** Change `FTLCONF_webserver_api_password` to a secure password before deployment.
+
+### Volumes
+
+- `./etc-pihole` - Pi-hole configuration files
+- `./etc-dnsmasq.d` - dnsmasq configuration files
+
+### Capabilities
+
+The container requires the following Linux capabilities:
+
+- `NET_ADMIN` - Network administration (required for DHCP)
+- `SYS_TIME` - System time modification (required for NTP)
+- `SYS_NICE` - Process priority adjustment
+
+## Usage
+
+### Starting the Stack
+
+```bash
+docker compose up -d
+```
+
+### Accessing the Web Interface
+
+Navigate to `http://<host-ip>/admin` and log in with the password set in `FTLCONF_webserver_api_password`.
+
+### Stopping the Stack
+
+```bash
+docker compose down
+```
+
+### Viewing Logs
+
+```bash
+docker compose logs -f pihole
+```
+
+## Network Configuration
+
+To use Pi-hole as your DNS server, configure your devices or router to use the host machine's IP address as the primary DNS server.
+
+### Option 1: Per-Device
+
+Set the DNS server on individual devices to point to the Pi-hole host IP.
+
+### Option 2: Router-Level
+
+Configure your router's DHCP settings to distribute the Pi-hole host IP as the DNS server to all clients.
+
+### Option 3: DHCP Server
+
+Disable DHCP on your router and let Pi-hole handle DHCP by configuring it through the web interface.
+
+## Image Version
+
+This stack uses Pi-hole version `2025.11.1`.