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

```text
/
├── 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.

```text
/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.
3.  **Healthchecks**: Every service MUST have a `healthcheck.sh` for verification.
4.  **Secrets**: NEVER commit secrets to Git. Use `env.example` as a template and populate `/opt/homelab/config/<service>/.env` on the host.

## 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`.