Bertram Family

Pi-hole Docker Deployment Protocol

// Mission Briefing: Deploy a network-wide DNS sinkhole using Pi-hole within a Docker container on a Windows 11 host system. This protocol includes integration of superior threat intelligence via Hagezi's curated blocklists to achieve maximum ad, tracker, and malware domain neutralization.

// Part 1: System Prerequisites & Environment Scan

Before deployment, the host system must meet operational parameters. Failure to comply will result in mission failure.

> Stage 1.1: Host System Specification

Required OS: Windows 11.
Critical Mandate: The host system must maintain continuous uptime. A system shutdown will result in a total network DNS blackout.

> Stage 1.2: Network Interface Configuration

The host system's network interface controller (NIC) must be assigned a static IPv4 address. Dynamic allocation via DHCP is unacceptable. For this protocol, we will use the placeholder 192.168.1.50. Substitute your designated static IP in all subsequent commands.

// Part 2: Docker Engine & WSL2 Subsystem Integration

We will provision the host with the Docker containerization engine, leveraging the Windows Subsystem for Linux 2 for optimal performance.

> Stage 2.1: CPU Virtualization Check

Access system BIOS/UEFI. Confirm hardware virtualization support (Intel VT-x / AMD-V) is enabled. This is a non-negotiable prerequisite.

> Stage 2.2: Docker Engine Acquisition & Deployment

1. Navigate to the Docker official comms channel: Docker Desktop Download.
2. Download the installer payload.
3. Execute the installer. The process will integrate the WSL2 subsystem automatically.
4. Post-installation, execute a full system reboot as prompted. Launch Docker Desktop to confirm service initialization.

// Part 3: Pi-hole Environment Deployment

Construct the directory structure for persistent data storage and define the container parameters via a Docker Compose manifest.

> Stage 3.1: Directory Structure Genesis

Execute the following commands in an elevated PowerShell terminal to create the required directory tree:


New-Item -Path "C:\" -Name "pihole" -ItemType Directory
New-Item -Path "C:\pihole" -Name "etc-pihole" -ItemType Directory
New-Item -Path "C:\pihole" -Name "etc-dnsmasq.d" -ItemType Directory

> Stage 3.2: Docker Compose Manifest Creation

1. Inside the C:\pihole directory, create a new file named docker-compose.yml.
2. Inject the following YAML configuration data into the manifest file:


version: "3"

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    environment:
      TZ: 'America/New_York'
      WEBPASSWORD: 'YourSecurePassword'
      PIHOLE_DNS_: '8.8.8.8;8.8.4.4'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      - NET_ADMIN
    restart: unless-stopped

SECURITY DIRECTIVE: Modify the TZ (Timezone) variable to your area of operations. Immediately change the default WEBPASSWORD to a high-entropy passphrase. I had to find the default password shown in the PiHole container's console. You can run the terminal and run pihole setpassword and make it empty, pressing enter.

// Part 4: Pi-hole Core Configuration & Intelligence Augmentation

With the environment staged, we will launch the container and inject superior threat intelligence feeds.

> Stage 4.1: Container Ignition

1. Open PowerShell with Administrator privileges.
2. Navigate to the deployment directory: cd C:\pihole
3. Execute the launch command:

docker-compose up -d

Docker will now pull the image layer and spin up the container in detached mode.

> Stage 4.2: Accessing the Command Interface

1. Open a web browser.
2. Navigate to the Pi-hole dashboard URL: http://192.168.1.50/admin (use your static IP).
3. Authenticate using the password defined in the manifest.

> Stage 4.3: Intelligence Augmentation (Adlist Integration)

1. In the Pi-hole interface, navigate to Group Management -> Adlists.
2. Input the following data feed URLs one by one into the "Address" field, clicking "Add" after each entry.

Multi PRO Feed:

https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/pro.txt

Hosts Feed:

https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/hosts.txt

Adblock Feed:

https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/adblock.txt

> Stage 4.4: Gravity Database Update

1. Navigate to Tools -> Update Gravity.
2. Click the large blue [ Update ] button.
3. Await process completion. The system will download and compile all domains from the new intelligence feeds. Monitor the debug output for a Success! message.

// Part 5: Network Traffic Redirection via Gateway

The final phase involves re-routing all network DNS queries through our newly deployed Pi-hole sinkhole by reconfiguring the primary network gateway (router).

> Stage 5.1: Gateway Interface Access

1. Access your router's admin panel via its IP address.
2. Authenticate with your administrator credentials.

> Stage 5.2: DHCP DNS Re-assignment

1. Navigate to the LAN section under "Advanced Settings".
2. Select the DHCP Server tab.
3. Locate the field labeled DNS Server.
4. Input the static IP of your Pi-hole host: 192.168.1.50.
5. CRITICAL: Ensure the secondary DNS server field is empty. Populating this field creates a bypass vulnerability.
6. Click [ Apply ] to commit the changes.

> Stage 5.3: Propagate DNS Changes

To force network clients to adopt the new DNS resolver, a DHCP lease renewal is required. The most effective method is a full reboot of all client devices (phones, PCs, smart TVs, etc.). Alternatively, toggling their network connection (Wi-Fi off/on) will suffice.

// Mission Complete

Pi-hole is now active and filtering all DNS traffic for your network. All connected clients are under its protection. Monitor the command interface for real-time statistics on neutralized threats. Welcome to a cleaner network stream.