infrastructure/docs/wip/GITOPS-CONTAINERS.md

GitOps for Container Management

Status: 💡 IDEA Depends On: Hardware upgrade completion Author: Kaloyan

---

Overview

Version control all container configurations to:

1. Track changes over time
2. Maintain consistency between XTRM-N5 and XTRM-N1
3. Enable automated deployments via Woodpecker CI
4. Recover from disasters quickly

---

Repository Structure

infrastructure/
├── configs/
│   ├── common/                    # Shared configs
│   │   ├── traefik/
│   │   │   └── dynamic.yml
│   │   └── authentik/
│   │       └── blueprints/
│   │
│   ├── xtrm-n5/                   # Production server
│   │   ├── docker/
│   │   │   ├── compose/           # docker-compose files
│   │   │   │   ├── netbox.yml
│   │   │   │   ├── gitea.yml
│   │   │   │   └── ...
│   │   │   ├── templates/         # Unraid XML templates
│   │   │   └── env/               # Environment files (.env.example)
│   │   ├── network/
│   │   │   └── docker-networks.json
│   │   └── unraid/
│   │       ├── shares.json
│   │       └── users.json
│   │
│   └── xtrm-n1/                   # Survival node
│       ├── docker/
│       │   └── compose/
│       │       ├── adguard.yml
│       │       ├── vaultwarden.yml
│       │       └── authentik-replica.yml
│       └── proxmox/
│           └── vm-configs/
│
└── .woodpecker.yml

---

Workflow

1. Change Detection

flowchart LR
    A[Edit config in Git] --> B[Push to main]
    B --> C[Woodpecker CI triggers]
    C --> D{Validate configs}
    D -->|Pass| E[Deploy to target server]
    D -->|Fail| F[Notify & block]

2. Drift Detection

flowchart LR
    A[Scheduled job] --> B[Export current state]
    B --> C{Compare to Git}
    C -->|Match| D[All good]
    C -->|Drift| E[Alert + PR with diff]

---

Implementation Phases

Phase 2.1: Export Current State

1. Export all docker-compose files
2. Export Unraid container templates (XML → YAML)
3. Export network configurations
4. Create initial commit

Phase 2.2: CI Pipeline

# .woodpecker.yml
pipeline:
  validate:
    image: docker:latest
    commands:
      - docker compose -f configs/xtrm-n5/docker/compose/*.yml config

  deploy-n5:
    image: alpine/ssh
    when:
      path: configs/xtrm-n5/**
    commands:
      - ssh root@192.168.31.2 "cd /path && docker compose up -d"
    secrets: [ssh_key]

  deploy-n1:
    image: alpine/ssh
    when:
      path: configs/xtrm-n1/**
    commands:
      - ssh root@xtrm-n1 "cd /path && docker compose up -d"
    secrets: [ssh_key]

Phase 2.3: Drift Detection

Scheduled Woodpecker job:

1. SSH to each server
2. Export current docker/network state
3. Compare to Git configs
4. Create issue/PR if drift detected

Phase 2.4: Unraid GUI Sync

Challenge: Changes made in Unraid GUI need to sync to Git

Solution Options:

Option	Pros	Cons
A: Webhook on change	Real-time sync	Complex, needs Unraid plugin
B: Scheduled export	Simple, reliable	Delay between change and commit
C: Prohibit GUI changes	Clean workflow	User friction

Recommended: Option B with daily scheduled exports

# Cron job on Unraid
0 4 * * * /boot/config/scripts/export-docker-config.sh

---

Secrets Management

Options:

Tool	Integration	Complexity
Woodpecker Secrets	Native	Low
Vaultwarden API	Via script	Medium
HashiCorp Vault	Enterprise	High

Recommended: Woodpecker Secrets for CI, .env.example in Git

# In docker-compose
services:
  app:
    env_file:
      - .env  # Not in Git, created from .env.example + secrets

---

Rollback Strategy

1. Git revert - Revert commit, CI redeploys previous version
2. Tagged releases - Deploy specific tag
3. Manual override - SSH and docker compose down/up

---

Related Documents

• UPGRADE-2026-HARDWARE.md - Hardware prerequisite