# Environment constraints

**Date:** 2026-01-10  
**Status:** Living document  
**Author:** Chester + FrankGPT

## Purpose

This document defines the hardware, software, and network constraints of the homelab environment. All playbooks and roles must respect these constraints.

---

## Network topology

> [!IMPORTANT]
> Current operational state is still a flat network on `10.0.0.0/24`.
> VLAN segmentation and target zone allocations in this document are migration targets,
> not fully applied runtime state.

| Parameter | Value |
| :--- | :--- |
| Subnet | `10.0.0.0/24` |
| Gateway | `10.0.0.2` |
| Primary DNS | `10.0.0.2` |
| Secondary DNS | `8.8.8.8` |
| Domain | `local` (optional) |

### IP allocation scheme

| Range | Purpose |
| :--- | :--- |
| `10.0.0.1` | Reserved |
| `10.0.0.2` | Gateway / Primary DNS |
| `10.0.0.3 - 10.0.0.199` | DHCP / General devices |
| `10.0.0.200 - 10.0.0.209` | Proxmox hosts (physical) |
| `10.0.0.210 - 10.0.0.219` | Swarm managers (VMs) |
| `10.0.0.220 - 10.0.0.229` | Swarm workers (VMs) / legacy AI nodes during migration |
| `10.0.0.230 - 10.0.0.239` | AI workstations |
| `10.0.0.240 - 10.0.0.248` | Reserved / Future |
| `10.0.0.249 - 10.0.0.250` | NAS devices |
| `10.0.0.251 - 10.0.0.254` | Docker hosts / Misc |

---

## Host categories

### Proxmox cluster (physical)

| Hostname | IP | Hardware | Notes |
| :--- | :---: | :--- | :--- |
| `pve01` | `10.0.0.201` | Lenovo SFF, 16 GB RAM, 512 GB NVMe | First node, 2× NICs |
| `pve02` | `10.0.0.202` | (future) | |
| `pve03` | `10.0.0.203` | (future) | |
| `pve04` | `10.0.0.204` | (future) | |
| `pve05` | `10.0.0.205` | (future) | |

**Constraints:**
- Proxmox VE 8.x or 9.x
- `ansible_user=root` for provisioning
- Python 3 available at `/usr/bin/python3`

### Swarm nodes (VMs on Proxmox)

| Role | Hostname pattern | IP range | Specs |
| :--- | :--- | :--- | :--- |
| Manager | `swarm-manager-X` | `.211 - .215` | 4 GB RAM, 2 vCPU, 32 GB disk |
| Worker | `swarm-worker-X` | `.221 - .225` | 4 GB RAM, 2 vCPU, 32 GB disk |

**Constraints:**
- Ubuntu 24.04 LTS (Noble)
- Docker CE installed via official repo
- `ansible_user=chester`

### AI workstations (physical)

| Hostname | IP | Hardware | Notes |
| :--- | :---: | :--- | :--- |
| `ai-lenovo` | `10.0.0.220` | Laptop, 12 GB GPU | Ubuntu Server |

**Constraints:**
- Ubuntu Server (not Desktop)
- GPU drivers managed separately
- `ansible_user=chester`

### Storage / NAS (appliances)

| Hostname | IP | Product | Notes |
| :--- | :---: | :--- | :--- |
| `synology` | `10.0.0.249` | Synology NAS | Proprietary Linux, limited shell |
| `terramaster` | `10.0.0.250` | TerraMaster NAS | Proprietary Linux, limited shell |

**Constraints:**
- **Caution required** — proprietary OS, not standard Ubuntu
- Use `ansible_scp_if_ssh=True` for Synology
- Avoid destructive commands; test in check mode first
- Limited Python support; prefer `raw` module when needed

### Controller (watchtower)

| Hostname | IP | Hardware | Notes |
| :--- | :---: | :--- | :--- |
| `localhost` | N/A | Raspberry Pi 5 | Ansible controller |

**Constraints:**
- `ansible_connection=local`
- Runs all playbooks from this host
- ARM64 architecture (consider when building containers)

---

## Software standards

| Component | Version | Notes |
| :--- | :--- | :--- |
| Ansible | 2.15+ | Core automation |
| Python | 3.10+ | Required on all managed hosts |
| Docker CE | Latest stable | Swarm mode |
| Proxmox VE | 8.x or 9.x | Hypervisor |
| Ubuntu | 24.04 LTS | Guest OS for VMs |

---

## Firewall / ports

| Port | Protocol | Purpose | Required on |
| :---: | :---: | :--- | :--- |
| 22 | TCP | SSH | All hosts |
| 8006 | TCP | Proxmox GUI | Proxmox hosts |
| 2377 | TCP | Swarm cluster mgmt | Swarm nodes |
| 7946 | TCP/UDP | Swarm node comm | Swarm nodes |
| 4789 | UDP | Swarm overlay network | Swarm nodes |

---

## Documentation mandate

> [!IMPORTANT]
> **FrankGPT core principle:** Documentation is not optional.
> 
> - Every decision must be recorded in `documentation/standards/`
> - Every playbook must have a header comment explaining usage
> - Every variable must be documented in defaults or group_vars
> - When in doubt, write it down

---

## Change log

| Date | Change | Author |
| :--- | :--- | :--- |
| 2026-01-10 | Initial creation | Chester + FrankGPT |