Pi4 Network Server - Printable Version

Code:
# Pi4 Network Server Head — Complete Reference

> Context document for AI-assisted setup and management of a Raspberry Pi 4 as an always-on network management appliance with touchscreen, wired Ethernet, and Docker-based service stack.

---

## 1. Hardware Baseline

**Board:** Raspberry Pi 4 Model B (2GB minimum, 4GB recommended, 8GB ideal for heavy Docker workloads)
**SoC:** Broadcom BCM2711, quad-core Cortex-A72 @ 1.5–1.8 GHz (arm64/aarch64)
**Network:** Gigabit Ethernet (true dedicated bus, not shared with USB like Pi3), dual-band 802.11ac Wi-Fi (not used — Ethernet only for server role)
**USB:** 2× USB 3.0, 2× USB 2.0 (for Zigbee/Z-Wave dongles, USB SSD, etc.)
**GPIO:** 40-pin header (available for relay control, sensors, HATs)
**Display:** DSI port for official 7" touchscreen (800×480, capacitive, 10-point multitouch)
**Power:** USB-C, 5.1V/3A minimum (use official PSU or quality 5V/3.5A to avoid undervoltage throttling — yellow lightning bolt icon = undervoltage)
**Power draw:** 5–15W depending on load; ~$3–8/month to run 24/7

### Storage Strategy

- **SD card:** Use only for boot (Class 10 / A2 minimum, 32GB+). SD cards suffer from write amplification and wear under Docker's overlay2 I/O. Container startup: 5–15s on SD vs 1–2s on SSD.
- **USB SSD (recommended):** Boot from USB SSD for dramatically better I/O. Use `rpi-eeprom-update` to enable USB boot, then flash OS to SSD via Raspberry Pi Imager. A $20–30 120GB SATA SSD via USB 3.0 adapter transforms performance and longevity.
- **If SD only:** Minimize writes — move Docker data dir, logs, and swap to a USB drive if possible. Reduce swappiness (`vm.swappiness=1`). Use `log2ram` to keep logs in RAM.

### Touchscreen Setup

**Official 7" Pi Touch Display:** DSI ribbon cable connection (labelled "DISPLAY" on Pi4). Adapter board mounts behind LCD; Pi4 mounts to adapter board standoffs. No additional drivers needed on Raspberry Pi OS.

**Cases with integrated touchscreen:**
- Official Pi Foundation case for 7" display (~$15)
- SmartiPi Touch 2 (adjustable angle, VESA mount)
- SunFounder 7" or 10" all-in-one kits (IPS, integrated case + cooling)
- 3D-printed "Raspberry Show" style cases (Echo Show–inspired desk form factor)
- 3.5" SPI screens exist but are low-res (480×320) and refresh-limited — use 7" DSI for any dashboard role

**Kiosk mode for dashboard display:**
Install minimal X server + Chromium in kiosk mode to auto-launch dashboards (Home Assistant, Grafana, Pi-hole admin, Portainer) on boot:
```
sudo apt install xserver-xorg xinit chromium-browser openbox
```
Configure `/etc/xdg/openbox/autostart` to launch Chromium fullscreen pointing at `http://localhost:PORT`. Use `unclutter` to hide the mouse cursor after idle. Disable screen blanking with `xset s off` and `xset -dpms` in xinitrc.

---

## 2. Base OS Installation

**OS:** Raspberry Pi OS Lite 64-bit (Bookworm-based, Debian 12). Lite = no desktop, headless. 64-bit required for modern Docker images (most publish arm64 only now). Verify with `uname -m` → must show `aarch64` not `armv7l`.

**Flashing:** Use Raspberry Pi Imager. Under "OS Customisation" (gear icon):
- Enable SSH (password or key)
- Set hostname (e.g., `piserver`)
- Set username/password (do NOT use default `pi`)
- Configure locale/timezone
- (Optional) Configure Wi-Fi for initial headless access, disable after Ethernet is confirmed

**First boot sequence:**
```bash
# SSH in from another machine
ssh [email protected]

# Full system update
sudo apt update && sudo apt full-upgrade -y
sudo reboot

# Set static IP (edit dhcpcd or NetworkManager depending on OS version)
# Bookworm uses NetworkManager by default:
sudo nmcli con mod "Wired connection 1" ipv4.addresses 192.168.1.X/24
sudo nmcli con mod "Wired connection 1" ipv4.gateway 192.168.1.1
sudo nmcli con mod "Wired connection 1" ipv4.dns "127.0.0.1"
sudo nmcli con mod "Wired connection 1" ipv4.method manual
sudo nmcli con up "Wired connection 1"
```

---

## 3. OS Hardening

### SSH Hardening
```bash
# Generate key pair on your workstation (not the Pi)
ssh-keygen -t ed25519

# Copy public key to Pi
ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]

# On the Pi — edit sshd_config
sudo nano /etc/ssh/sshd_config
# Set:
#  PermitRootLogin no
#  PasswordAuthentication no
#  PubkeyAuthentication yes
#  Port 2222  (change from default 22)
sudo systemctl restart sshd
```

### Firewall (UFW)
```bash
sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 2222/tcp  # SSH (your custom port)
sudo ufw allow 53/tcp    # DNS (Pi-hole)
sudo ufw allow 53/udp    # DNS (Pi-hole)
sudo ufw allow 80/tcp    # HTTP (dashboards)
sudo ufw allow 443/tcp    # HTTPS
sudo ufw allow 51820/udp  # WireGuard VPN
sudo ufw enable
```

### Fail2Ban
```bash
sudo apt install fail2ban -y
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo nano /etc/fail2ban/jail.local
# Under [sshd]:
#  enabled = true
#  port = 2222
#  maxretry = 3
#  bantime = 3600
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
```

### Additional Hardening
- Disable unused services: `sudo systemctl disable bluetooth`, `sudo systemctl disable avahi-daemon` (unless using .local mDNS)
- Automatic security updates: `sudo apt install unattended-upgrades -y`
- Remove default `pi` user if it exists: `sudo deluser pi`
- Set `HISTSIZE=1000` and `HISTFILESIZE=2000` in `.bashrc`
- Consider AIDE (file integrity monitoring) for paranoid setups

---

## 4. Docker & Container Management

### Docker Installation
```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group change
docker --version
docker compose version  # v2 included automatically
```

### Key Docker Concepts for Pi4
- Pi4 runs `arm64` (aarch64). `docker pull` auto-selects correct architecture from multi-arch images.
- LinuxServer.io (LSIO) images are reliable ARM64 builds.
- If SD-card storage: move Docker root to USB SSD:
  ```bash
  sudo systemctl stop docker
  sudo rsync -aP /var/lib/docker/ /mnt/ssd/docker/
  # Edit /etc/docker/daemon.json:
  { "data-root": "/mnt/ssd/docker" }
  sudo systemctl start docker
  ```
- Use `restart: unless-stopped` on all services for auto-recovery after reboot.

### Portainer (Container GUI)
```yaml
# docker-compose.yml
services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    ports:
      - "9443:9443"
      - "9000:9000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    restart: unless-stopped
volumes:
  portainer_data:
```
Access at `https://piserver.local:9443`. Provides web GUI for managing all Docker containers, images, volumes, networks. Supports Docker Compose stack deployment from the UI.

### CasaOS (Alternative)
CasaOS is a beginner-friendly GUI layer over Docker. One-line install: `curl -fsSL https://get.casaos.io | sudo bash`. Provides an app store UI for deploying containers (Pi-hole, Nextcloud, Jellyfin, etc.) without writing compose files. Good for non-technical household members. Runs on port 80 by default.

---

## 5. DNS & Ad Blocking — Pi-hole + Unbound

### Pi-hole (Network-Wide Ad Blocker)

Pi-hole acts as DNS sinkhole. All devices on network point DNS to Pi4. Ads, trackers, malware domains get null responses — never load. Blocks 35–45% of all DNS requests in a typical home network (40,000–80,000 queries/day blocked for ~12 devices).

**Pi-hole v6 (current as of 2026):** Major rewrite. FTL has embedded web server (no more lighttpd). Single config file `/etc/pihole/pihole.toml`. Docker image switched from Debian to Alpine (113MB → 38MB).

```yaml
# Docker Compose for Pi-hole
services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80/tcp"
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "CHANGEME"
    volumes:
      - pihole_data:/etc/pihole
      - pihole_dnsmasq:/etc/dnsmasq.d
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
volumes:
  pihole_data:
  pihole_dnsmasq:
```

**Bare-metal install (alternative):**
```bash
curl -sSL https://install.pi-hole.net | bash
# Follow interactive installer
# Set password: pihole -a -p YourPassword
```

**Network integration — two methods:**
1. **Router DNS method:** Set router's DHCP DNS server to Pi4's static IP. All devices auto-use Pi-hole. No per-device config.
2. **Pi-hole as DHCP server:** Disable DHCP on router, enable in Pi-hole admin. Pi-hole assigns IPs and DNS. Better hostname resolution but more complex.

**Blocklists:** Default Steven Black unified list is good baseline. Add community lists from firebog.net for expanded coverage. Admin dashboard: `http://piserver.local:8080/admin`.

### Unbound (Recursive DNS Resolver)

Without Unbound, Pi-hole forwards queries to upstream DNS (Cloudflare, Google, etc.) — those providers see every domain you resolve. Unbound resolves recursively by walking the DNS hierarchy from root servers. No third-party sees your full query history.

**Architecture:** Pi-hole listens on port 53 → filters ads → forwards allowed queries to Unbound on port 5335 → Unbound resolves recursively against authoritative nameservers.

```bash
sudo apt install unbound -y

# Create Pi-hole-optimized config
sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf
```

```yaml
server:
    verbosity: 0
    interface: 127.0.0.1
    port: 5335
    do-ip4: yes
    do-udp: yes
    do-tcp: yes
    do-ip6: no
    prefer-ip6: no
    harden-glue: yes
    harden-dnssec-stripped: yes
    use-caps-for-id: no
    edns-buffer-size: 1232
    prefetch: yes
    num-threads: 1
    so-rcvbuf: 1m
    private-address: 192.168.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8
```

```bash
sudo systemctl enable unbound
sudo systemctl start unbound
# Test: dig pi-hole.net @127.0.0.1 -p 5335
```

In Pi-hole admin → Settings → DNS: set Custom Upstream DNS to `127.0.0.1#5335`. Remove all other upstream servers.

**Trade-off:** First lookup for any domain is slower (Unbound must walk hierarchy). Subsequent queries are cached locally. For most home networks the difference is imperceptible.

### DNSSEC
Unbound validates DNSSEC by default. Protects against DNS cache poisoning and response spoofing. Does NOT encrypt queries in transit (use DoT/DoH at the Unbound level for that, but it's optional and adds complexity).

---

## 6. VPN — WireGuard / Tailscale

### WireGuard via PiVPN (Self-Hosted VPN)

WireGuard: modern VPN protocol, ~4,000 lines of code (vs OpenVPN's 70,000+), faster, simpler, ChaCha20 encryption. Pi4 handles 20–50 simultaneous connections comfortably.

```bash
curl -L https://install.pivpn.io | bash
# Select WireGuard (not OpenVPN)
# Choose your Ethernet interface
# Set VPN port (default 51820/UDP)
# Choose DNS provider (select Pi-hole if running)
# Use your public IP or dynamic DNS hostname
```

**Port forwarding required:** Forward UDP 51820 on your router to Pi4's static IP.

**Client management:**
```bash
pivpn add      # Create client profile (generates .conf + QR code)
pivpn list      # Show all clients
pivpn remove    # Remove a client
pivpn qr        # Show QR code for mobile import
```

**Split vs Full tunnel:**
- Split tunnel: only home network traffic goes through VPN (access LAN remotely)
- Full tunnel: ALL traffic routes through VPN (secure public Wi-Fi)
- Create both profiles for different use cases

**Pi-hole + WireGuard combo:** Route VPN DNS through Pi-hole. Ad blocking follows you everywhere — mobile, laptop on public Wi-Fi, travel.

### Tailscale (Zero-Config Mesh VPN)

Alternative to self-hosted WireGuard. No port forwarding needed. Built on WireGuard protocol but with automatic NAT traversal, key management, and mesh networking.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Authenticate via URL provided
```

**Key features:**
- Mesh network: devices connect directly peer-to-peer
- Subnet router: Pi4 can expose entire LAN to your tailnet (`sudo tailscale up --advertise-routes=192.168.1.0/24`)
- Exit node: route all traffic through Pi4 when remote
- MagicDNS: access devices by hostname
- ACLs: control which devices can see what
- Free tier: up to 100 devices, 3 users

**Pi4 as subnet router:** All devices on tailnet can access your home LAN through the Pi4 — NAS, printers, other PCs — without installing Tailscale on each.

**Disable key expiry** for always-on devices (Pi4, NAS): Tailscale admin console → Machines → select Pi → Disable key expiry.

---

## 7. Smart Home — Home Assistant

### Overview

Home Assistant (HA) is open-source, privacy-first home automation. Emphasis on LOCAL control — devices controlled directly over LAN without cloud dependency. Runs on Pi4 via HAOS image or Docker container. 2,000+ integrations.

### Installation Methods

**Method 1: Home Assistant OS (HAOS) — dedicated Pi4**
Flash the HAOS image directly. Pi4 becomes a dedicated HA appliance. Includes Supervisor for add-on management. Best integration, simplest updates, but Pi4 can't easily run other services.

**Method 2: Docker container — shared Pi4 (recommended for this use case)**
```yaml
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    privileged: true
    volumes:
      - ha_config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
volumes:
  ha_config:
```
Access at `http://piserver.local:8123`. Loses Supervisor/add-on system but runs alongside Pi-hole, WireGuard, monitoring, etc.

### Offline / Local Control

HA was built for local-first operation. Works without internet if devices use local protocols:
- **Zigbee:** Requires USB coordinator dongle ($15–25, e.g., SONOFF Zigbee 3.0, Conbee II). Use ZHA integration (built-in) or Zigbee2MQTT. Fully local. Wide device support (lights, sensors, switches, locks).
- **Z-Wave:** Requires USB Z-Wave stick (e.g., Aeotec Z-Stick Gen5+). Use Z-Wave JS integration. Fully local. Strong for locks, thermostats, switches.
- **Wi-Fi (local):** Devices running Tasmota, ESPHome firmware communicate over local network only. No cloud.
- **Thread/Matter:** Newer protocol standard. Local-first by design. Pi4 can act as Thread border router with appropriate hardware.

**MQTT broker (Mosquitto):** Central message bus for IoT. Lightweight publish/subscribe protocol. All Zigbee2MQTT and many other integrations route through it.
```bash
sudo apt install mosquitto mosquitto-clients -y
sudo systemctl enable mosquitto
```
Or via Docker:
```yaml
services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - mosquitto_config:/mosquitto/config
      - mosquitto_data:/mosquitto/data
    restart: unless-stopped
```

### Zigbee2MQTT (Alternative to ZHA)
Bridges Zigbee coordinator to MQTT. More device support than ZHA, runs outside HA (survives HA restarts), web dashboard for device management.
```yaml
services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    volumes:
      - z2m_data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8082:8080"
    environment:
      TZ: "America/New_York"
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: unless-stopped
```

### Touchscreen Integration
Run Chromium in kiosk mode (see Section 1) pointing at `http://localhost:8123`. Create a dedicated HA user with a custom dashboard optimized for touch (large buttons, status cards). Auto-login via HA trusted networks or long-lived access token.

---

## 8. Network Monitoring

### Uptime Kuma (Service Monitor)
Lightweight, open-source. Monitors HTTP, TCP, DNS, ICMP ping, Docker containers. Real-time dashboard, historical stats (24h/7d/30d). 90+ notification channels (Telegram, Discord, email, Gotify). Pi4 handles 50–100+ monitors easily. ~76,000 GitHub stars, current version 2.1.3 (Feb 2026). Integrates with Home Assistant as of HA 2025.8 (binary sensors per monitor).

```yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    ports:
      - "3001:3001"
    volumes:
      - uptime_kuma_data:/app/data
    restart: unless-stopped
```

### Grafana + Prometheus (Advanced Monitoring)
Full metrics stack. Prometheus scrapes time-series data; Grafana visualizes. Pre-built Raspberry Pi dashboards (CPU, memory, disk I/O, temperature). Can ingest Uptime Kuma metrics via Prometheus exporter.

```yaml
services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3030:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    restart: unless-stopped
```

### Gotify (Push Notifications)
Self-hosted notification server. Receives alerts from Uptime Kuma, Grafana, custom scripts. Android app available. Replaces dependency on Pushover/Ntfy cloud services.

### Recommended Monitoring Stack
"Holy trinity" for home labs: Uptime Kuma (service uptime) + Beszel or Pulse (host metrics) + Gotify (alerting). Grafana/Prometheus for deep-dive dashboards if desired.

---

## 9. PC Cluster / Network Orchestration

### Using Pi4 as Control Plane for Desktop PCs

The Pi4 can serve as the management/control plane node while desktop PCs (x86_64) serve as worker nodes. Two main approaches:

### Approach A: Docker Swarm (Simpler)
- Pi4 runs as Swarm manager
- Desktop PCs join as worker nodes
- Manages containerized services across the cluster
- Built-in load balancing and scaling
- Good for: distributed web apps, batch processing, CI/CD runners
```bash
# On Pi4 (manager):
docker swarm init --advertise-addr 192.168.1.X
# Shows join token

# On each desktop PC (worker):
docker swarm join --token SWMTKN-xxxxx 192.168.1.X:2377
```
**Mixed architecture caveat:** Images must be multi-arch (arm64 + amd64). Pi4 manager runs arm64; x86 workers run amd64. Use multi-arch images or constrain services to specific node architectures via placement constraints.

### Approach B: K3s Lightweight Kubernetes (More Powerful)
K3s: single binary (~70MB), includes API server, scheduler, controller manager, kubelet, containerd, Flannel CNI, Traefik ingress, CoreDNS. Supports mixed arm64/amd64 clusters natively.

```bash
# On Pi4 (control plane):
curl -sfL https://get.k3s.io | sh -
# Get join token:
cat /var/lib/rancher/k3s/server/node-token

# On each desktop PC (worker):
curl -sfL https://get.k3s.io | K3S_URL=https://piserver:6443 K3S_TOKEN=XXX sh -
```

**Pi4 resource budget for K3s control plane:**
- K3s server: ~500MB RAM
- System: ~300MB RAM
- Available for workloads: ~2.7GB (on 4GB Pi4)
- OS buffer/cache: ~500MB

**Use cases for Pi4-managed PC cluster:**
- Distributed build/CI runners (GitHub Actions self-hosted, Drone)
- Distributed rendering (Blender render farm)
- Game server hosting across machines
- Distributed storage (GlusterFS across nodes)
- Learning enterprise orchestration patterns

### Wake-on-LAN (WoL)
Pi4 can wake sleeping/powered-off PCs on demand:
```bash
sudo apt install wakeonlan -y
wakeonlan AA:BB:CC:DD:EE:FF  # MAC address of target PC
```
Combine with Home Assistant automations or cron jobs. Useful for spinning up worker nodes only when needed (power savings). Requires WoL enabled in each PC's BIOS/UEFI and network adapter settings.

---

## 10. Reverse Proxy

### Traefik (Recommended for Docker)
Auto-discovers Docker containers, auto-configures routing, auto-manages Let's Encrypt TLS certificates. Label-based configuration — no manual config file updates per service.

```yaml
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
    ports:
      - "80:80"
      - "8180:8080"  # Traefik dashboard
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped
```

Other services add Traefik labels:
```yaml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.pihole.rule=Host(`pihole.local`)"
```

### Nginx Proxy Manager (Alternative)
Web GUI for reverse proxy config. Simpler for those uncomfortable with label/file-based config. Supports Let's Encrypt, access lists, custom locations.

### Local DNS Names
Use Pi-hole's "Local DNS → DNS Records" to create custom hostnames:
- `pihole.home` → 192.168.1.X
- `grafana.home` → 192.168.1.X
- `ha.home` → 192.168.1.X

Combined with reverse proxy, access services by name instead of IP:port.

---

## 11. Additional Services Worth Running

| Service | Purpose | Port | Notes |
|---|---|---|---|
| **Nextcloud** | Self-hosted cloud storage/sync | 8443 | Pi4 handles light use; heavy use benefits from SSD |
| **Vaultwarden** | Bitwarden-compatible password manager | 8081 | Very lightweight, perfect for Pi4 |
| **Nginx/Caddy** | Static site hosting | 80/443 | Host personal website directly |
| **Gitea** | Self-hosted Git | 3000 | Lightweight GitHub alternative |
| **Jellyfin** | Media server | 8096 | Pi4 can direct-play most formats; no hardware transcoding on Pi4 GPU |
| **Syncthing** | File sync between devices | 8384 | Replaces Dropbox/Google Drive |
| **Homer/Homarr** | Dashboard/homepage | 8083 | Landing page linking all services |
| **Node-RED** | Visual automation flows | 1880 | Bridges HA, MQTT, APIs, scripts |
| **n8n** | Workflow automation | 5678 | Self-hosted Zapier alternative |
| **Ntfy/Gotify** | Push notifications | 8085 | Self-hosted push service |
| **Speedtest Tracker** | ISP speed monitoring | 8765 | Tracks download/upload/latency over time |

---

## 12. Maintenance & Best Practices

### Backups
```bash
# Backup all Docker volumes
sudo tar czf /mnt/backup/docker-volumes-$(date +%F).tar.gz /var/lib/docker/volumes/

# Or use restic for incremental encrypted backups
sudo apt install restic -y
restic init --repo /mnt/backup/restic-repo
restic backup /var/lib/docker/volumes/ /etc/pihole/ /etc/unbound/
```

### Updates
```bash
# System
sudo apt update && sudo apt upgrade -y

# Docker images
docker compose pull    # Pull latest images
docker compose up -d  # Recreate with new images
docker image prune -f  # Clean old images

# Pi-hole
pihole -up  # If bare-metal install

# Automate with cron:
# 0 3 * * 0 docker compose -f /home/youruser/docker-compose.yml pull && docker compose -f /home/youruser/docker-compose.yml up -d
```

### Monitoring Pi Health
```bash
# CPU temperature (throttles at 80°C, shuts down at 85°C)
vcgencmd measure_temp

# Voltage/throttling status
vcgencmd get_throttled
# 0x0 = all good
# 0x50005 = throttled due to undervoltage

# Memory
free -h

# Disk
df -h

# Docker resource usage
docker stats --no-stream
```

### Cooling
Pi4 throttles under sustained load without cooling. At minimum: aluminum heatsinks on SoC and RAM. Better: active fan case (e.g., Argon ONE, Flirc, GeeKPi) or PoE HAT with fan. For always-on server duty, active cooling is strongly recommended.

### Reliability
- Use quality USB-C PSU (5.1V/3A minimum, official recommended)
- UPS recommended (small USB UPS or PoE with UPS switch). NUT (Network UPS Tools) on Pi4 can signal other machines to shut down gracefully on power loss.
- Enable watchdog timer: add `dtparam=watchdog=on` to `/boot/firmware/config.txt`, install `watchdog` package. Auto-reboots on system hang.
- Monitor SD card health with `smartctl` (if SSD) or watch for I/O errors in `dmesg`

---

## 13. Complete Docker Compose Stack (Reference)

Single compose file for the core service stack:

```yaml
version: "3.8"

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80/tcp"
    environment:
      TZ: "${TZ}"
      WEBPASSWORD: "${PIHOLE_PASSWORD}"
      PIHOLE_DNS_: "127.0.0.1#5335"
    volumes:
      - pihole_data:/etc/pihole
      - pihole_dnsmasq:/etc/dnsmasq.d
    restart: unless-stopped
    cap_add:
      - NET_ADMIN

  wireguard:
    image: linuxserver/wireguard:latest
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      PUID: 1000
      PGID: 1000
      TZ: "${TZ}"
      SERVERURL: "${WG_SERVER_URL}"
      SERVERPORT: 51820
      PEERS: "phone,laptop,tablet"
      PEERDNS: "192.168.1.X"  # Pi-hole IP
    volumes:
      - wireguard_config:/config
      - /lib/modules:/lib/modules
    ports:
      - "51820:51820/udp"
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    privileged: true
    volumes:
      - ha_config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped

  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - mosquitto_config:/mosquitto/config
      - mosquitto_data:/mosquitto/data
    restart: unless-stopped

  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    ports:
      - "3001:3001"
    volumes:
      - uptime_kuma_data:/app/data
    restart: unless-stopped

  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    restart: unless-stopped

volumes:
  pihole_data:
  pihole_dnsmasq:
  wireguard_config:
  ha_config:
  mosquitto_config:
  mosquitto_data:
  uptime_kuma_data:
  portainer_data:
```

Create `.env` file alongside:
```
TZ=America/New_York
PIHOLE_PASSWORD=changeme
WG_SERVER_URL=your.dynamic-dns.com
```

---

## 14. Network Architecture Diagram

```
[Internet] → [Router/Modem]
                  │
                  ├── Ethernet → [Pi4 Server Head] (192.168.1.X, static)
                  │                  ├── Pi-hole (DNS port 53)
                  │                  ├── Unbound (recursive DNS, port 5335, localhost only)
                  │                  ├── WireGuard VPN (UDP 51820)
                  │                  ├── Home Assistant (port 8123)
                  │                  ├── Mosquitto MQTT (port 1883)
                  │                  ├── Zigbee2MQTT (port 8082) ← USB Zigbee coordinator
                  │                  ├── Uptime Kuma (port 3001)
                  │                  ├── Portainer (port 9443)
                  │                  ├── Grafana (port 3030)
                  │                  ├── Traefik reverse proxy (port 80/443)
                  │                  └── [Touchscreen: kiosk dashboard]
                  │
                  ├── Ethernet/Wi-Fi → [Desktop PCs] (Docker Swarm/K3s workers)
                  ├── Wi-Fi → [Phones, Tablets, Laptops]
                  ├── Wi-Fi/Zigbee → [Smart Home Devices]
                  └── Wi-Fi → [Smart TVs, Consoles, IoT]

Router DNS setting → Pi4 IP (all devices auto-use Pi-hole)
WireGuard clients → Pi4 (remote access + ad blocking away from home)
K3s/Swarm workers → Pi4 control plane (orchestration)
```

---

## 15. Quick-Start Checklist

1. [ ] Flash Raspberry Pi OS Lite 64-bit to SD card (or USB SSD)
2. [ ] Enable SSH, set hostname, set user/password in Imager
3. [ ] Boot Pi4, connect Ethernet, SSH in
4. [ ] Set static IP on Pi4
5. [ ] System update + reboot
6. [ ] Harden: SSH keys, change port, UFW, Fail2Ban
7. [ ] Install Docker + Docker Compose
8. [ ] Deploy Pi-hole (set router DNS to Pi4 IP)
9. [ ] Install Unbound, configure as Pi-hole upstream
10. [ ] Deploy Portainer for container management
11. [ ] Deploy WireGuard (PiVPN) or install Tailscale
12. [ ] Deploy Home Assistant + Mosquitto (if doing smart home)
13. [ ] Deploy Uptime Kuma for monitoring
14. [ ] Set up touchscreen kiosk mode for dashboard
15. [ ] Configure backups (cron + restic or tar)
16. [ ] (Optional) Set up K3s/Docker Swarm for PC cluster
17. [ ] (Optional) Deploy additional services (Vaultwarden, Nextcloud, etc.)

---

## 16. Key Port Reference

| Port | Service | Protocol |
|------|---------|----------|
| 22/2222 | SSH | TCP |
| 53 | Pi-hole DNS | TCP/UDP |
| 80 | HTTP / Traefik / CasaOS | TCP |
| 443 | HTTPS / Traefik | TCP |
| 1883 | Mosquitto MQTT | TCP |
| 3001 | Uptime Kuma | TCP |
| 3030 | Grafana | TCP |
| 5335 | Unbound (localhost) | TCP/UDP |
| 8080 | Pi-hole Admin | TCP |
| 8082 | Zigbee2MQTT | TCP |
| 8123 | Home Assistant | TCP |
| 9000/9443 | Portainer | TCP |
| 51820 | WireGuard VPN | UDP |