# 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
│   ├── 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.

```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)
└── 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`.