homelab-codex-ws/docs/deployment.md

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.