homelab-codex-ws/README.md

# Homelab Codex

GitOps-lite orchestration for a distributed homelab environment.

## Architecture

The homelab consists of several nodes connected via a Tailscale internal mesh.

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

## Repository Structure

- `docs/`: [Infrastructure Standards](docs/standards.md) and [Deployment Conventions](docs/deployment.md).
- `hosts/`: Host-specific configurations and service assignments.
- `services/`: Reusable Docker Compose service definitions.
- `scripts/`: Deployment and management scripts.

## Getting Started

1.  **Standardization**: Follow the [Infrastructure Standards](docs/standards.md).
2.  **Deployment**: See [Deployment Conventions](docs/deployment.md) for how to roll out changes.
3.  **SATURN**: Remember that SATURN is the only node where commits should be made.

## Documentation Index

- [Infrastructure Standards](docs/standards.md)
- [Deployment Conventions](docs/deployment.md)
- [Hardware](docs/hardware.md)
- [Networking](docs/networking.md)
- [Services](docs/services.md)

---
*Note: This repository documents the state of the homelab. Runtime state lives outside the repository in `/opt/homelab`.*