41 lines
1.7 KiB
Markdown
41 lines
1.7 KiB
Markdown
|
# Deployment Conventions
|
||
|
|
|
||
|
|
This document describes the GitOps-lite deployment process for the homelab.
|
||
|
|
|
||
|
|
## Principles
|
||
|
|
|
||
|
|
1. **Git as Source of Truth**: All infrastructure definitions (Docker Compose, configurations) are stored in Git.
|
||
|
|
2. **Unidirectional Flow**: Changes flow from **SATURN** (commit node) to execution nodes.
|
||
|
|
3. **Lightweight**: No complex orchestrators (no Kubernetes). Use `docker compose` and simple shell scripts.
|
||
|
|
4. **Tailscale Mesh**: All hosts are connected via Tailscale, allowing secure communication without public port exposure.
|
||
|
|
|
||
|
|
## Deployment Process
|
||
|
|
|
||
|
|
### 1. Preparation (on SATURN)
|
||
|
|
|
||
|
|
- Modify or create service definitions in `services/`.
|
||
|
|
- Assign services to hosts by creating/updating `hosts/<hostname>/services.txt` (or similar mapping).
|
||
|
|
- Commit and push changes to the Forgejo instance.
|
||
|
|
|
||
|
|
### 2. Deployment (on Execution Node)
|
||
|
|
|
||
|
|
Execution nodes run a deployment script (e.g., via cron or manual trigger) that:
|
||
|
|
|
||
|
|
1. Performs a `git pull` from the source of truth.
|
||
|
|
2. Identifies services assigned to this host.
|
||
|
|
3. Symlinks or copies `services/<service>/docker-compose.yml` to `/opt/homelab/services/`.
|
||
|
|
4. Runs `docker compose up -d --remove-orphans`.
|
||
|
|
|
||
|
|
## Host-Local Overrides
|
||
|
|
|
||
|
|
If a service requires host-specific configuration (e.g., unique device paths for GPUs on SOLARIA):
|
||
|
|
|
||
|
|
1. Create a `docker-compose.override.yml` in `/opt/homelab/config/<service>/`.
|
||
|
|
2. The deployment script should include this override if it exists.
|
||
|
|
|
||
|
|
## Secrets Management
|
||
|
|
|
||
|
|
- **Do NOT commit secrets to Git.**
|
||
|
|
- Secrets should be placed in `/opt/homelab/config/<service>/.env` on the target host.
|
||
|
|
- The deployment script should ensure these are sourced by Docker Compose.
|