From 2a3720a42891f10e77165def657f1942054f9533 Mon Sep 17 00:00:00 2001
From: alvis <allogn@gmail.com>
Date: Sun, 8 Mar 2026 07:03:29 +0000
Subject: [PATCH] Move network config to Network page, add Pi-hole pipeline
 section

---
 Agap-Installation.md | 43 +--------------------------
 Network.md           | 71 +++++++++++++++++++++++++++++++++-----------
 2 files changed, 55 insertions(+), 59 deletions(-)

diff --git a/Agap-Installation.md b/Agap-Installation.md
index 366b6d0..f60e1a8 100644
--- a/Agap-Installation.md
+++ b/Agap-Installation.md
@@ -17,48 +17,7 @@ Required mount points:
 
 ## 2. Network
 
-### Netplan (bridge)
-
-Edit `/etc/netplan/50-cloud-init.yaml`:
-
-```yaml
-network:
-  bridges:
-    br0:
-      interfaces: [enp4s0]
-      dhcp4: true
-  version: 2
-```
-
-```bash
-sudo netplan apply
-```
-
-> MAC address changes after bridge setup — router may assign a new IP.
-> Interface name (`enp4s0`) may differ after hardware changes — check with `ip link show`.
-
-### Caddy (reverse proxy)
-
-[Install Caddy](https://caddyserver.com/docs/install#debian-ubuntu-raspbian), then configure `/etc/caddy/Caddyfile`:
-
-```
-haos.alogins.net  { reverse_proxy http://192.168.1.141:8123 }
-vi.alogins.net    { reverse_proxy localhost:2283 }
-zb.alogins.net    { reverse_proxy localhost:81 }
-git.alogins.net   { reverse_proxy localhost:3000 }
-ai.alogins.net    { reverse_proxy localhost:3125 }
-ntfy.alogins.net  { reverse_proxy localhost:8840 }
-```
-
-(See `/etc/caddy/Caddyfile` for full config including VPN and other services.)
-
-```bash
-sudo systemctl enable --now caddy
-```
-
-**Requirements:**
-- Ports **80** and **443** forwarded on the router (source and target, remote IP empty)
-- Port **10051** forwarded for Zabbix active agent connections
+See [[Network]] for full setup: Netplan bridge, Caddy reverse proxy, Pi-hole DNS, and port forwarding requirements.
 
 ## 3. GPU & Docker
 
diff --git a/Network.md b/Network.md
index f907494..955c402 100644
--- a/Network.md
+++ b/Network.md
@@ -1,40 +1,49 @@
 # Network
 
-## Netplan
+## Netplan (bridge)
 
-Edit `/etc/netplan/*.yaml`:
+Edit `/etc/netplan/50-cloud-init.yaml`:
 
 ```yaml
-bridges:
-  br0:
-    interfaces: [enp3s0]
+network:
+  bridges:
+    br0:
+      interfaces: [enp4s0]
+      dhcp4: true
+  version: 2
 ```
 
-Apply:
-
 ```bash
 sudo netplan apply
 ```
 
 > MAC address changes after bridge setup — router may assign a new IP.
-> Interface name (`enp3s0`) may change after hardware reconfiguration.
+> Interface name (`enp4s0`) may differ after hardware changes — check with `ip link show`.
 
-## Caddy
+## Caddy (reverse proxy)
 
 [Install](https://caddyserver.com/docs/install#debian-ubuntu-raspbian) | [Docs](https://caddyserver.com/docs/getting-started)
 
-Reload config:
+Config: `/etc/caddy/Caddyfile`
 
-```bash
-curl localhost:2019/load \
-  -H "Content-Type: application/json" \
-  -d @caddy.json
+```
+haos.alogins.net  { reverse_proxy http://192.168.1.141:8123 }
+vi.alogins.net    { reverse_proxy localhost:2283 }
+zb.alogins.net    { reverse_proxy localhost:81 }
+git.alogins.net   { reverse_proxy localhost:3000 }
+ai.alogins.net    { reverse_proxy localhost:3125 }
+ntfy.alogins.net  { reverse_proxy localhost:8840 }
 ```
 
-### Requirements
+(See `/etc/caddy/Caddyfile` for full config including VPN and other services.)
 
-- Ports **80** and **443** must both be forwarded (source and target)
-- Leave remote IP empty in router port forwarding for intranet access
+```bash
+sudo systemctl enable --now caddy
+```
+
+**Port forwarding requirements:**
+- Ports **80** and **443** forwarded on the router (source and target, remote IP empty)
+- Port **10051** forwarded for Zabbix active agent connections
 
 ### TLS debugging
 
@@ -42,3 +51,31 @@ curl localhost:2019/load \
 curl -v http://yourdomain.net/.well-known/acme-challenge/test
 # Expect HTTP 200
 ```
+
+## Pi-hole (DNS ad-blocking)
+
+Pi-hole runs as a Docker container on a **macvlan** network, giving it its own IP on the LAN (`192.168.1.2`). This allows it to bind to port 53 without conflicting with the host.
+
+### Architecture
+
+```
+[LAN clients] → DNS → 192.168.1.2 (pihole, macvlan on br0)
+                         ↓ (upstream)
+                    8.8.8.8 / 1.1.1.1
+```
+
+The host (`br0`) and Pi-hole (`macvlan-br0`) are on the same physical network but **cannot communicate directly** due to macvlan isolation. The host uses its router as DNS instead.
+
+### Setup
+
+```bash
+cd ~/agap_git/pihole
+docker compose up -d
+```
+
+Pi-hole data: `/mnt/ssd/dbs/pihole`
+Web UI: `http://192.168.1.2/admin` (password: set via `FTLCONF_webserver_api_password`)
+
+### Router config
+
+Set the router's DNS server to `192.168.1.2` so all LAN clients use Pi-hole automatically.