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