Skip to content

Commit 39c5f8f

Browse files
riccjohnriccjohn
committed
Add pihole
1 parent c9240a9 commit 39c5f8f

File tree

8 files changed

+1044
-2
lines changed

8 files changed

+1044
-2
lines changed

‎.env.example‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Home Network Server Configuration
2+
# Copy this file to .env and update with your values
3+
4+
# Domain Configuration
5+
DOMAIN=home.local
6+
# Timezone (use tz database names, e.g., America/New_York, Europe/London, Asia/Tokyo)
7+
# Find your timezone: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
8+
TZ=America/Chicago
9+
10+
# Pi-hole Configuration
11+
PIHOLE_PASSWORD=changeme
12+
PIHOLE_DNS=8.8.8.8;1.1.1.1
13+
ADMIN_EMAIL=
14+
15+
# Future Service Configuration (for Phase 2+)
16+
# MEDIA_PATH=./media
17+
# ACME_EMAIL=admin@example.com
18+
19+
# Server IP (required for host networking mode)
20+
# Set this to your server's IP address on your local network
21+
SERVER_IP=192.168.0.243

‎README.md‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,45 @@ See [PLANNING.md](./PLANNING.md) for the complete implementation plan, including
3636

3737
## Current Status
3838

39-
🚧 **Planning Phase** - See [PLANNING.md](./PLANNING.md) for implementation roadmap.
39+
✅ **Phase 1: Pi-hole MVP** - Ready for deployment
40+
41+
See [PLANNING.md](./PLANNING.md) for the complete implementation roadmap.
42+
43+
## Services
44+
45+
### Pi-hole
46+
47+
Network-wide DNS and ad-blocking service.
48+
49+
**Quick Setup:**
50+
1. Run `./setup.sh` (auto-detects server IP)
51+
2. Configure router DHCP DNS to use your server IP
52+
3. Start: `docker compose up -d`
53+
4. Access: `http://YOUR_SERVER_IP/admin`
54+
55+
**Documentation:**
56+
- [Pi-hole Setup & Configuration](./docs/pihole-setup.md)
57+
- [Pi-hole Troubleshooting](./docs/pihole-troubleshooting.md)
58+
59+
**Scripts:**
60+
- `scripts/pihole/test-pihole.sh` - Test Pi-hole functionality
61+
- `scripts/pihole/diagnose-pihole.sh` - Network diagnostic tool
62+
- `scripts/pihole/update-server-ip.sh` - Update server IP in .env
63+
64+
## Project Structure
65+
66+
```
67+
home-network/
68+
├── docker-compose.yml # Main orchestration file
69+
├── .env # Environment variables (gitignored)
70+
├── setup.sh # Initial setup script
71+
├── docs/ # Service-specific documentation
72+
│ └── pihole-*.md
73+
├── scripts/ # Service-specific scripts
74+
│ └── pihole/
75+
└── [service]/ # Service data directories
76+
```
4077

4178
## License
4279

4380
[Add your license here]
44-

‎docker-compose.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
services:
2+
pihole:
3+
container_name: pihole
4+
image: pihole/pihole:latest
5+
hostname: pihole
6+
domainname: ${DOMAIN:-home.local}
7+
network_mode: host
8+
environment:
9+
# Timezone (configure via TZ in .env file, e.g., TZ=America/New_York, TZ=Europe/London)
10+
TZ: ${TZ:-America/New_York}
11+
# Pi-hole password
12+
FTLCONF_webserver_api_password: ${PIHOLE_PASSWORD:-changeme}
13+
WEBPASSWORD: ${PIHOLE_PASSWORD:-changeme}
14+
# DNS Settings
15+
PIHOLE_DNS: ${PIHOLE_DNS:-8.8.8.8;1.1.1.1}
16+
# Set the IP of the host machine for Pi-hole to know its own address
17+
# Configure via SERVER_IP in .env file (e.g., SERVER_IP=192.168.0.243)
18+
SERVERIP: ${SERVER_IP:-192.168.0.243}
19+
# Interface settings - 'eth0' is often correct on Linux hosts
20+
INTERFACE: eth0
21+
# IPv6 settings (disable if not needed)
22+
IPv6: "false"
23+
# Admin interface settings
24+
ADMIN_EMAIL: ${ADMIN_EMAIL:-}
25+
volumes:
26+
- ./pihole/etc:/etc/pihole
27+
- ./pihole/etc-dnsmasq.d:/etc/dnsmasq.d
28+
restart: unless-stopped
29+
cap_add:
30+
- NET_ADMIN

‎docs/pihole-setup.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Pi-hole Setup Guide
2+
3+
## Prerequisites
4+
5+
- Docker and Docker Compose installed
6+
- Ubuntu Server (or compatible Linux distribution)
7+
- Router with configurable DNS settings
8+
9+
## Installation Steps
10+
11+
1. **Run the setup script:**
12+
```bash
13+
./setup.sh
14+
```
15+
This will:
16+
- Check Docker installation
17+
- Create `.env` file from template
18+
- Auto-detect and set `SERVER_IP`
19+
- Create necessary directories
20+
21+
2. **Configure environment variables:**
22+
Edit the `.env` file created by the setup script:
23+
```bash
24+
nano .env
25+
```
26+
- Set `PIHOLE_PASSWORD` to a strong password
27+
- `SERVER_IP` is automatically detected and set by the setup script
28+
- Adjust `TZ` to your timezone
29+
- Modify `DOMAIN` if needed (default: home.local)
30+
31+
**Note:** If your server's IP changes, run `scripts/pihole/update-server-ip.sh` to update it automatically.
32+
33+
3. **Start Pi-hole:**
34+
```bash
35+
docker compose up -d
36+
```
37+
38+
**Note:** Pi-hole uses `host` networking mode to see real client IP addresses in the query log. This allows you to identify which devices are making DNS queries, rather than all queries appearing to come from the Docker gateway.
39+
40+
4. **Configure your router:**
41+
- Log into your router's admin interface
42+
- Find **DHCP Server Settings** (not just router DNS settings!)
43+
- Set **Primary DNS** to your server's IP address
44+
- Set **Secondary DNS** to `8.8.8.8` or `1.1.1.1`
45+
- Save and restart router if needed
46+
47+
⚠️ **Important:** You need to configure **DHCP DNS settings**, not just router DNS. These are often separate settings in router configuration.
48+
49+
5. **Access Pi-hole admin:**
50+
- Open browser to `http://YOUR_SERVER_IP/admin`
51+
- Login with password from `.env` file
52+
53+
6. **Verify it's working:**
54+
- See [Testing Pi-hole](#testing-pi-hole) below
55+
- Or run: `scripts/pihole/test-pihole.sh`
56+
57+
## Testing Pi-hole
58+
59+
### Quick Test Script
60+
61+
Run the test script on your server:
62+
```bash
63+
./scripts/pihole/test-pihole.sh
64+
```
65+
66+
### Manual Testing
67+
68+
#### Method 1: Check Pi-hole Dashboard
69+
70+
1. **View Query Log:**
71+
- Go to `http://YOUR_SERVER_IP/admin`
72+
- Navigate to **Query Log** (left sidebar)
73+
- You should see DNS queries from devices on your network
74+
- Look for queries from different devices (phones, computers, etc.)
75+
76+
2. **Check Statistics:**
77+
- Go to **Dashboard** in Pi-hole admin
78+
- Check the **Queries** counter - it should be increasing
79+
- Check **Blocked** counter - should show blocked ad/tracking domains
80+
- **Clients** should show devices using Pi-hole
81+
82+
#### Method 2: Test DNS Resolution
83+
84+
**On the server:**
85+
```bash
86+
# Test DNS resolution through Pi-hole
87+
dig @127.0.0.1 google.com
88+
89+
# Or using nslookup
90+
nslookup google.com 127.0.0.1
91+
```
92+
93+
**On a client device:**
94+
```bash
95+
# Linux/Mac
96+
dig @YOUR_SERVER_IP google.com
97+
nslookup google.com YOUR_SERVER_IP
98+
99+
# Check what DNS your device is using
100+
# Linux
101+
cat /etc/resolv.conf
102+
103+
# Mac
104+
scutil --dns | grep nameserver
105+
106+
# Windows
107+
ipconfig /all | findstr "DNS Servers"
108+
```
109+
110+
#### Method 3: Test Ad-Blocking
111+
112+
1. **Visit a test site with ads:**
113+
- Visit `https://www.forbes.com` or `https://www.cnn.com`
114+
- Check if ads are blocked (you may see blank spaces or "blocked" messages)
115+
116+
2. **Test known ad domains:**
117+
- Visit `http://pi.hole` in your browser
118+
- You should see the Pi-hole block page
119+
- Or test: `http://doubleclick.net` (should be blocked)
120+
121+
3. **Check blocked domains in Pi-hole:**
122+
- Go to **Query Log** in Pi-hole admin
123+
- Look for entries marked as **Blocked** (red)
124+
- Common blocked domains: `doubleclick.net`, `googleadservices.com`, `googlesyndication.com`
125+
126+
#### Method 4: Verify Device DNS Settings
127+
128+
**Check if devices are using Pi-hole DNS:**
129+
130+
**Android:**
131+
- Settings → Wi-Fi → Long press your network → Modify network → Advanced → IP settings
132+
- Check DNS 1 and DNS 2 (should be your server IP)
133+
134+
**iPhone/iPad:**
135+
- Settings → Wi-Fi → Tap (i) next to your network → Configure DNS
136+
- Should show your server IP
137+
138+
**Mac:**
139+
```bash
140+
scutil --dns | grep nameserver
141+
```
142+
143+
**Linux:**
144+
```bash
145+
cat /etc/resolv.conf
146+
```
147+
148+
**Windows:**
149+
```cmd
150+
ipconfig /all
151+
```
152+
153+
### Expected Results
154+
155+
✅ **Working correctly if:**
156+
- Query Log shows queries from multiple devices
157+
- Statistics show increasing query counts
158+
- Blocked counter shows blocked domains
159+
- DNS resolution works (google.com resolves)
160+
- Ad domains are blocked (doubleclick.net returns 0.0.0.0 or fails)
161+
- Devices show your server IP as DNS server
162+
163+
❌ **Not working if:**
164+
- Query Log is empty (devices not using Pi-hole)
165+
- No blocked domains (ad-blocking not working)
166+
- DNS resolution fails
167+
- Devices show different DNS servers
168+
169+
## Troubleshooting
170+
171+
For detailed troubleshooting, see [Pi-hole Troubleshooting](./pihole-troubleshooting.md)
172+
173+
**Quick fixes:**
174+
175+
- **Can't access Pi-hole web interface:**
176+
- Check firewall: `sudo ufw allow 80/tcp`
177+
- Verify container is running: `docker compose ps`
178+
- Check logs: `docker compose logs pihole`
179+
180+
- **Devices not using Pi-hole DNS:**
181+
- Run diagnostic: `./scripts/pihole/diagnose-pihole.sh`
182+
- See [Troubleshooting Guide](./pihole-troubleshooting.md) for router configuration
183+
184+
- **DNS not resolving:**
185+
- Check Pi-hole logs: `docker compose logs pihole`
186+
- Verify upstream DNS servers in Pi-hole settings
187+
- Test DNS directly: `dig @YOUR_SERVER_IP google.com`
188+
- Check firewall: `sudo ufw allow 53/tcp && sudo ufw allow 53/udp`
189+

0 commit comments

Comments
 (0)