claude-home/server-configs/networking/nginx-proxy-manager-pihole.md

Nginx Proxy Manager + Pi-hole Setup

Host: 10.10.0.16 Services: Nginx Proxy Manager, Pi-hole DNS

This host runs both NPM (reverse proxy) and Pi-hole (DNS server) as Docker containers.

Quick Info

Property	Value
IP	10.10.0.16
User	cal
NPM Container	nginx-proxy-manager_app_1
Pi-hole Container	pihole
Pi-hole Web	http://10.10.0.16/admin

Services

Nginx Proxy Manager

• Container: nginx-proxy-manager_app_1
• Web UI: http://10.10.0.16:81
• Ports: 80, 443, 81
• Database: SQLite at /data/database.sqlite
• Config: /data/nginx/
• Logs: /data/logs/

Pi-hole

• Container: pihole
• Web UI: http://10.10.0.16/admin
• Ports: 53 (DNS), 80 (Web)
• Config: /etc/pihole/
• Custom DNS: /etc/pihole/custom.list

Architecture

┌─────────────┐
│   Clients   │
│ (Homelab)   │
└──────┬──────┘
       │ DNS Query: termix.manticorum.com?
       ▼
┌─────────────────────┐
│  Pi-hole (10.10.0.16)│
│  Returns: 10.10.0.16 │  ← Local DNS override
└──────┬──────────────┘
       │ HTTPS Request
       ▼
┌──────────────────────────┐
│  NPM (10.10.0.16)        │
│  - Checks access list    │  ← Sees real client IP (10.0.0.206)
│  - Terminates SSL        │
│  - Proxies to backend    │
└──────┬───────────────────┘
       │ HTTP Proxy
       ▼
┌──────────────────────┐
│  Backend Service     │
│  (e.g., Termix)      │
│  10.10.0.210:8180    │
└──────────────────────┘

DNS Sync Automation

Problem Solved

When accessing homelab services by domain name (e.g., termix.manticorum.com), DNS would resolve to Cloudflare IPs, causing traffic to hairpin through the internet. This broke IP-based access lists since NPM would see your public IP instead of your internal IP.

Solution

Automatically sync all NPM proxy hosts to Pi-hole's local DNS, pointing them to NPM's internal IP (10.10.0.16).

Sync Script

Location: /home/cal/scripts/npm-pihole-sync.sh (on 10.10.0.16) Repository: server-configs/networking/scripts/npm-pihole-sync.sh

The script:

1. Queries NPM's SQLite database for all enabled proxy hosts
2. Extracts domain names
3. Creates Pi-hole custom DNS entries pointing to NPM (10.10.0.16)
4. Reloads Pi-hole DNS

Usage:

# Dry run (preview changes)
ssh cal@10.10.0.16 /home/cal/scripts/npm-pihole-sync.sh --dry-run

# Apply changes
ssh cal@10.10.0.16 /home/cal/scripts/npm-pihole-sync.sh

Automation:

• Runs hourly via cron: 0 * * * * /home/cal/scripts/npm-pihole-sync.sh >> /home/cal/logs/npm-pihole-sync.log 2>&1
• Logs: /home/cal/logs/npm-pihole-sync.log

Deployment:

# Copy script to server
scp server-configs/networking/scripts/npm-pihole-sync.sh cal@10.10.0.16:/home/cal/scripts/

# Make executable
ssh cal@10.10.0.16 "chmod +x /home/cal/scripts/npm-pihole-sync.sh"

# Test
ssh cal@10.10.0.16 "/home/cal/scripts/npm-pihole-sync.sh --dry-run"

# Apply
ssh cal@10.10.0.16 "/home/cal/scripts/npm-pihole-sync.sh"

Cloudflare Real IP Configuration

To support external access through Cloudflare while maintaining proper IP detection for access lists, NPM is configured to trust Cloudflare's IP ranges and read the real client IP from the CF-Connecting-IP header.

Configuration (in /etc/nginx/nginx.conf inside NPM container):

# Trust internal networks
set_real_ip_from 10.0.0.0/8;
set_real_ip_from 172.16.0.0/12;
set_real_ip_from 192.168.0.0/16;

# Trust Cloudflare IPs
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;

# Read real IP from Cloudflare header
real_ip_header CF-Connecting-IP;
real_ip_recursive on;

This ensures:

• Local access: Client IP seen correctly (e.g., 10.0.0.206)
• External access via Cloudflare: Real public IP seen (not Cloudflare's proxy IP)

Access Lists

NPM supports IP-based access restrictions. Common patterns:

Internal Only

Allows access only from local networks:

allow 10.0.0.0/24;
allow 10.10.0.0/24;
deny all;

Use this for:

• Internal services (Termix, n8n, OmniTools)
• Admin interfaces
• Development environments

Cloudflare Only

Trusts Cloudflare's authenticated access (Cloudflare Access/Zero Trust):

• No IP restrictions needed
• Cloudflare handles authentication
• Use for public services behind Cloudflare Access

Management

Access Containers

# SSH to host
ssh cal@10.10.0.16

# Access NPM container
docker exec -it nginx-proxy-manager_app_1 bash

# Access Pi-hole container
docker exec -it pihole bash

NPM Commands

# View proxy host configs
docker exec nginx-proxy-manager_app_1 ls /data/nginx/proxy_host/

# View specific proxy host
docker exec nginx-proxy-manager_app_1 cat /data/nginx/proxy_host/21.conf

# Test nginx config
docker exec nginx-proxy-manager_app_1 nginx -t

# Reload nginx
docker exec nginx-proxy-manager_app_1 nginx -s reload

# View access logs
docker exec nginx-proxy-manager_app_1 tail -f /data/logs/proxy-host-21_access.log

Pi-hole Commands

# View custom DNS
docker exec pihole cat /etc/pihole/custom.list

# Restart DNS
docker exec pihole pihole restartdns reload

# View logs
docker logs pihole -f

# Pi-hole status
docker exec pihole pihole status

Query NPM Database

# List all proxy hosts
docker exec nginx-proxy-manager_app_1 python3 -c "
import sqlite3
conn = sqlite3.connect('/data/database.sqlite')
cursor = conn.cursor()
cursor.execute('SELECT id, domain_names, forward_host, forward_port FROM proxy_host')
for row in cursor.fetchall():
    print(row)
conn.close()
"

Troubleshooting

403 Forbidden Errors

Symptom: Getting 403 errors when accessing services with "Internal Only" access list.

Causes:

1. Hairpinning through Cloudflare: DNS resolving to Cloudflare IPs instead of local

   • Fix: Ensure Pi-hole has local DNS override (run sync script)
   • Check: dig +short service.manticorum.com @10.10.0.16 should return 10.10.0.16

2. Access list doesn't include your subnet: Your IP not in allowed ranges

   • Fix: Add your subnet to access list (e.g., 10.0.0.0/24)
   • Check: View access logs to see what IP NPM is seeing

3. Real IP not detected: NPM seeing proxy/Cloudflare IP instead of client IP

   • Fix: Ensure Cloudflare IPs are in set_real_ip_from and real_ip_header CF-Connecting-IP is set
   • Check: Access logs should show your real IP, not Cloudflare's

Debug Steps:

# Check what IP NPM sees
docker exec nginx-proxy-manager_app_1 tail -20 /data/logs/proxy-host-21_access.log

# Check DNS resolution
dig +short termix.manticorum.com @10.10.0.16

# Check access list in proxy host config
docker exec nginx-proxy-manager_app_1 cat /data/nginx/proxy_host/21.conf | grep -A 10 "Access Rules"

DNS Not Resolving Locally

Symptom: Domains still resolve to Cloudflare IPs.

Causes:

1. DNS sync not run or failed
2. Desktop not using Pi-hole for DNS
3. DNS cache on desktop

Fix:

# Re-run sync
ssh cal@10.10.0.16 /home/cal/scripts/npm-pihole-sync.sh

# Check Pi-hole has the record
ssh cal@10.10.0.16 "docker exec pihole cat /etc/pihole/custom.list | grep termix"

# Verify DNS server on desktop
cat /etc/resolv.conf  # Should show 10.10.0.16

# Flush DNS cache on desktop
sudo resolvectl flush-caches  # SystemD
# or
sudo systemd-resolve --flush-caches

Related Documentation

• Gitea Server - Uses NPM proxy
• n8n Automation - Uses NPM proxy
• Akamai NPM - Public-facing NPM instance

Deployment Date

Created: 2026-02-04 By: Claude Code NPM Version: (check with docker exec nginx-proxy-manager_app_1 cat /app/package.json | grep version) Pi-hole Version: (check with docker exec pihole pihole -v)