# 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

```mermaid
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

```mermaid
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

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

```bash
# 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

```yaml
# 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