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
├── inventory/          # Topology and templates
├── services/           # Normalized service definitions
│   └── <service>/
│       ├── docker-compose.yml
│       ├── service.yaml
│       ├── README.md
│       ├── env.example
│       └── healthcheck.sh
├── 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)
│   └── <service>/
│       ├── .env        # Merged environment variables
│       └── overrides/  # Local configuration overrides
└── logs/               # Service logs

Service Standards

1. Normalization: Every service MUST follow the services/<service>/ layout.
2. Metadata: Every service MUST have a service.yaml defining its operational contract. This is the primary source of truth for AI agents.
3. Healthchecks: Every service MUST have a healthcheck.sh for verification. Agents use this to emit stability events.
4. Actionability: Any automated recovery action proposed by an agent must be backed by a service.yaml definition.
5. Secrets: NEVER commit secrets to Git. Use env.example as a template and populate /opt/homelab/config/<service>/.env on the host. Agents must treat these as "black box" configurations.

Docker Compose Standards

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

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.