docs/topology.md

@@ -0,0 +1,34 @@
+# Homelab Topology
+
+## Nodes
+
+| Node | Role |
+|---|---|
+| SATURN | Control and development node |
+| PIHA | Infrastructure and monitoring node |
+| SOLARIA | AI and compute node |
+| VPS | Public ingress and edge node |
+| CHELSTY | Virtualization and Home Assistant node |
+
+## Architecture Principles
+
+- Git is the source of truth.
+- SATURN is the primary orchestration and commit node.
+- Runtime state lives outside repositories.
+- Tailscale provides internal mesh networking.
+- Docker Compose remains the deployment model.
+- Public ingress is centralized on VPS.
+- Deployment uses lightweight shell scripts.
+- Avoid Kubernetes and heavy orchestration frameworks.
+
+## Runtime Layout
+
+Runtime data should live under:
+
+/opt/homelab
+
+with separated:
+- services
+- data
+- config
+- logs

hosts/chelsty/host.yaml

@@ -0,0 +1,16 @@
+hostname: chelsty
+
+roles:
+  - hypervisor
+  - homeassistant
+  - staging
+
+network:
+  tailscale_ip: 100.122.201.22
+
+runtime:
+  root: /opt/homelab
+
+deployment:
+  mode: pull
+  managed_by: saturn

hosts/piha/host.yaml

@@ -0,0 +1,15 @@
+hostname: piha
+
+roles:
+  - infra
+  - monitoring
+
+network:
+  tailscale_ip: 100.108.208.3
+
+deployment:
+  mode: pull
+  managed_by: saturn
+
+runtime:
+  root: /opt/homelab

hosts/saturn/host.yaml

@@ -0,0 +1,14 @@
+hostname: saturn
+
+roles:
+  - control
+  - development
+
+network:
+  tailscale_ip: 100.121.168.72
+
+deployment:
+  mode: orchestrator
+
+runtime:
+  root: /opt/homelab

hosts/solaria/host.yaml

@@ -0,0 +1,15 @@
+hostname: solaria
+
+roles:
+  - compute
+  - ai
+
+network:
+  tailscale_ip: 100.100.231.104
+
+deployment:
+  mode: pull
+  managed_by: saturn
+
+runtime:
+  root: /opt/homelab

hosts/vps/host.yaml

@@ -0,0 +1,15 @@
+hostname: vps
+
+roles:
+  - edge
+  - ingress
+
+network:
+  tailscale_ip: 100.95.58.48
+
+deployment:
+  mode: pull
+  managed_by: saturn
+
+runtime:
+  root: /opt/homelab

inventory/topology.yaml

@@ -0,0 +1,35 @@
+topology:
+  mesh: tailscale
+  git_provider: forgejo
+
+deployment:
+  mode: pull
+  orchestrator: saturn
+
+nodes:
+
+  saturn:
+    roles:
+      - control
+      - development
+
+  piha:
+    roles:
+      - infra
+      - monitoring
+
+  solaria:
+    roles:
+      - compute
+      - ai
+
+  vps:
+    roles:
+      - edge
+      - ingress
+
+  chelsty:
+    roles:
+      - hypervisor
+      - homeassistant
+      - staging