From 8fbcec2b1e811875c49e522c581223d8392571b1 Mon Sep 17 00:00:00 2001
From: "Rodrigo Rodriguez (Pragmatismo)" <me@rodrigorodriguez.com>
Date: Fri, 17 Apr 2026 11:21:33 -0300
Subject: [PATCH] docs: Add Incus container network configuration guide

- Document static IPv4 address assignment procedure
- Add troubleshooting table for common network issues
- List standard IP assignments for all containers
- Include step-by-step guide for creating new containers with static IPs
- Add models container IP reservation (10.157.134.251)
---
 PROD.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/PROD.md b/PROD.md
index dda3d0a..e5b51cf 100644
--- a/PROD.md
+++ b/PROD.md
@@ -267,6 +267,102 @@ $ ssh user@<hostname> "sudo incus exec system -- curl -s --cacert /opt/gbo/conf/
 
 ---
 
+## Incus Container Network Configuration
+
+### Static IPv4 Address Assignment
+
+When creating new containers, they may not receive IPv4 addresses automatically. To assign permanent static IPs:
+
+**Step 1: Set static IP on the container device**
+```bash
+# Choose an unused IP in the 10.157.134.x range
+sudo incus config device set <container> eth0 ipv4.address 10.157.134.<last_octet>
+```
+
+**Step 2: Configure network inside the container**
+```bash
+sudo incus exec <container> -- bash -c 'cat > /etc/network/interfaces << EOF
+auto lo
+iface lo inet loopback
+
+auto eth0
+iface eth0 inet static
+    address 10.157.134.<last_octet>
+    netmask 255.255.255.0
+    gateway 10.157.134.1
+    dns-nameservers 8.8.8.8 8.8.4.4
+EOF'
+```
+
+**Step 3: Restart the container**
+```bash
+sudo incus restart <container>
+```
+
+**Step 4: Verify IPv4 assignment**
+```bash
+sudo incus list <container> -c n4
+sudo incus exec <container> -- ip addr show eth0
+```
+
+### Common Network Issues
+
+| Problem | Symptom | Fix |
+|---------|---------|-----|
+| No IPv4 | Container shows empty IPV4 column | Set static IP via `incus config device set` |
+| IP conflict | "IP address already defined on another NIC" | Choose different IP, check `incus list` |
+| Can't reach internet | DNS fails inside container | Configure DNS in `/etc/network/interfaces` |
+| IPv6 only | Has IPv6 but no IPv4 | Add static IPv4 config as above |
+| DHCP not working | dhclient fails or returns 169.254.x.x | Use static IP assignment instead |
+
+### Container IP Reference
+
+Standard IP assignments (10.157.134.x range):
+- `system`: 10.157.134.196
+- `tables`: 10.157.134.174
+- `vault`: 10.157.134.250
+- `cache`: 10.157.134.230
+- `drive`: 10.157.134.206
+- `directory`: 10.157.134.240
+- `llm`: 10.157.134.205
+- `vectordb`: 10.157.134.210
+- `models`: 10.157.134.251 (reserved)
+- `dns`: 10.157.134.214
+- `proxy`: 10.157.134.241
+- `email`: 10.157.134.40
+- `meet`: 10.157.134.220
+
+### Creating a New Container with Static IP
+
+```bash
+# Create container
+sudo incus launch images:debian/12 <new-container>
+
+# Set static IP (before first boot is best)
+sudo incus config device set <new-container> eth0 ipv4.address 10.157.134.<unused>
+
+# Configure networking inside container
+sudo incus exec <new-container> -- bash -c 'cat > /etc/network/interfaces << EOF
+auto lo
+iface lo inet loopback
+
+auto eth0
+iface eth0 inet static
+    address 10.157.134.<unused>
+    netmask 255.255.255.0
+    gateway 10.157.134.1
+    dns-nameservers 8.8.8.8
+EOF'
+
+# Restart to apply
+sudo incus restart <new-container>
+
+# Verify
+sudo incus list <new-container>
+```
+
+---
+
 ## Troubleshooting Quick Reference
 
 **GLIBC mismatch (`GLIBC_2.39 not found`):** The binary was compiled on the CI runner (glibc 2.41) not inside the system container (glibc 2.36). The CI workflow must SSH into the system container to build. Check `botserver.yaml` to confirm this.