Pi-hole DNS Setup Skill

Configure Pi-hole local DNS records for local network resolution of temet.ai domains.

Quick Start

Run automated DNS setup from domains.toml:

cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply

Or manually add a single DNS record:

# Get Pi IP
PI_IP=$(hostname -I | awk '{print $1}')

# Test DNS resolution
dig @localhost pihole.temet.ai +short

Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Instructions
   • 3.1 Detect Pi IP Address
   • 3.2 Get Domains from Configuration
   • 3.3 Apply DNS Changes
   • 3.4 Verify DNS Resolution
   • 3.5 Router DNS Reminder
4. Supporting Files
5. Expected Outcomes
6. Requirements
7. Red Flags to Avoid

When to Use This Skill

Explicit Triggers:

• “Set up Pi-hole DNS”
• “Configure local DNS”
• “Add DNS record for [domain]”
• “Set up DNS entries”
• “Make [service].temet.ai resolve locally”

Implicit Triggers:

• After adding a new service to domains.toml
• When local resolution fails for temet.ai domains
• Setting up a fresh Pi-hole installation
• Migrating services to new IP addresses

Debugging Triggers:

• “DNS not resolving”
• “Can’t access [service].temet.ai on local network”
• “dig returns wrong IP”
• “Works remotely but not locally”

What This Skill Does

1. Detects Pi IP – Auto-discovers the Raspberry Pi’s local IP address
2. Reads Configuration – Gets domain list from domains.toml
3. Updates DNS – Configures Pi-hole with local DNS entries via docker-compose.yml
4. Verifies Resolution – Tests DNS resolution works correctly
5. Provides Guidance – Reminds about router DNS configuration

Instructions

3.1 Detect Pi IP Address

Get the Pi’s local IP automatically:

hostname -I | awk '{print $1}'

Expected output: 192.168.68.135 (or similar)

Alternative methods if needed:

# From network interface
ip -4 addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'

# From Pi-hole container environment
docker exec pihole printenv | grep PIHOLE_INTERFACE

3.2 Get Domains from Configuration

Read domains from domains.toml:

# List all configured services with DNS entries
./scripts/manage-domains.sh list

Or parse directly:

grep -E "^subdomain = |^dns_ip = " /home/dawiddutoit/projects/network/domains.toml

Current domains defined in domains.toml:

3.3 Apply DNS Changes

Automated Method (Recommended):

cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply

This runs generate-pihole-dns.py which:

1. Reads domains.toml
2. Updates FTLCONF_dns_hosts in docker-compose.yml
3. Restarts Pi-hole to apply changes

Manual DNS Entry (Single Domain):

If you need to add a single entry without full apply:

# Edit docker-compose.yml FTLCONF_dns_hosts section
# Then restart Pi-hole
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml restart pihole

How DNS Configuration Works:

Pi-hole v6 uses FTLCONF_dns_hosts environment variable for custom DNS:

environment:
  FTLCONF_dns_hosts: |
    192.168.68.135 pihole.temet.ai
    192.168.68.135 jaeger.temet.ai
    192.168.68.105 sprinkler.temet.ai

3.4 Verify DNS Resolution

After applying changes, verify DNS works:

Test individual domain:

dig @localhost pihole.temet.ai +short
# Expected: 192.168.68.135

Test all configured domains:

for domain in pihole jaeger langfuse ha code webhook; do
  echo -n "$domain.temet.ai -> "
  dig @localhost $domain.temet.ai +short
done

Test from another device on the network:

# Replace 192.168.68.135 with Pi's IP
dig @192.168.68.135 pihole.temet.ai +short

Check Pi-hole DNS logs:

docker exec pihole pihole -t
# Watch live DNS queries

3.5 Router DNS Reminder

Important: For DNS to work network-wide, configure your router:

1. Set router’s DHCP to use Pi-hole as primary DNS:

   • Primary DNS: 192.168.68.135 (Pi’s IP)
   • Secondary DNS: 1.1.1.1 (fallback)

2. Or configure each device individually to use Pi-hole DNS

Verify device is using Pi-hole:

# On the device, check what DNS server it's using
cat /etc/resolv.conf
# Should show: nameserver 192.168.68.135

Supporting Files

Expected Outcomes

Success:

• All domains resolve to correct IPs locally
• dig @localhost domain.temet.ai returns expected IP
• Services accessible at https://domain.temet.ai on local network

Partial Success:

• DNS works from Pi but not from other devices
• Cause: Router not configured to use Pi-hole as DNS

Failure Indicators:

• dig returns NXDOMAIN -> DNS entry not configured
• dig returns wrong IP -> Stale configuration
• Pi-hole not responding -> Container not running

Requirements

Environment:

• Pi-hole container running: docker ps | grep pihole
• Docker Compose available
• domains.toml configured

Tools needed:

• Read (configuration files)
• Bash (dig, docker commands)
• Grep (parsing domains)

Red Flags to Avoid

• Do not add DNS entries directly to Pi-hole web UI (use domains.toml)
• Do not forget to restart Pi-hole after config changes
• Do not skip the router DNS configuration reminder
• Do not use 127.0.0.1 as DNS IP (use actual Pi IP)
• Do not assume DNS propagates instantly (may take 1-2 minutes)
• Do not forget IoT devices may need different IPs (sprinkler -> 192.168.68.105)

Notes

• DNS entries are stored in docker-compose.yml FTLCONF_dns_hosts
• The generate-pihole-dns.py script reads domains.toml and updates docker-compose.yml
• Local DNS resolution allows fast LAN access without internet roundtrip
• Remote access uses Cloudflare DNS (separate from Pi-hole)
• Always verify DNS after changes with dig @localhost domain +short