82 lines
3 KiB
Markdown
82 lines
3 KiB
Markdown
# 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`.
|