69 lines
2.2 KiB
Markdown
69 lines
2.2 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
|
||
|
|
│ ├── 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`.
|