homelab-codex-ws/docs/standards.md

Infrastructure Standards

This document defines the standards and conventions for the homelab GitOps-lite environment.

Host Architecture

Host	Role	Description
SATURN	Primary Node	Development, orchestration, and git source of truth (commit node).
SOLARIA	Compute Node	GPU, inference, and heavy compute workloads.
PIHA	Infra Node	Core infrastructure services, automation, and monitoring.
VPS	Edge Node	Public ingress, reverse proxy, and edge services.

Directory Layout

Repository Layout

/
├── docs/               # Infrastructure documentation
├── hosts/              # Host-specific configurations
│   ├── saturn/
│   ├── solaria/
│   ├── piha/
│   └── vps/
├── services/           # Reusable service definitions (Docker Compose)
├── scripts/            # Management and deployment scripts
└── README.md

Runtime Layout (on Execution Nodes)

Runtime state must live outside the repository to keep it immutable and clean.

/opt/homelab/
├── services/           # Active docker-compose files (deployed from git)
├── data/               # Persistent volume data (backed up)
├── config/             # Host-local overrides and secrets (not in git)
└── logs/               # Service logs

Docker Compose Standards

1. File Naming: Use docker-compose.yml.
2. Container Naming: service-name.
3. Restarts: Always use restart: unless-stopped.
4. Networking:
   • Use tailscale internal mesh for inter-host communication.
   • Expose ports only when necessary.
5. Volumes: Use named volumes or absolute paths to /opt/homelab/data/service-name.

Environment Variables

• .env: Default environment variables (checked into git if safe).
• .env.local: Host-specific overrides (not in git).

Naming Conventions

• Hosts: All caps (SATURN, SOLARIA, PIHA, VPS).
• Services: Kebab-case (e.g., ollama-server).
• Containers: Match service name.

Deployment Flow

1. Changes are committed and pushed to SATURN.
2. Execution nodes (SOLARIA, PIHA, VPS) pull changes.
3. Deployment scripts trigger docker compose up -d.