XTRM-Unraid
b250493d5a
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
New Structure: - 01-NETWORK-MAP.md - Network topology, IPs, Docker networks, services - 02-SERVICES-CRITICAL.md - DNS, Auth, Routing (P0/P1 services) - 03-SERVICES-OTHER.md - All non-critical services - 04-HARDWARE-INVENTORY.md - Physical devices and specs - 05-CHANGELOG.md - Major events only New Folders: - docs/archive/ - Legacy docs (read-only reference) - docs/wip/ - Planned changes and ideas - UPGRADE-2026-HARDWARE.md - N5 Air + N100 migration plan - GITOPS-CONTAINERS.md - Phase 2 container GitOps Changes: - Moved all 22 legacy docs to archive/ - Consolidated container IPs, physical map, and services into single network map - Extracted critical vs non-critical service classification - Simplified changelog to major events only Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
181 lines
4.2 KiB
Markdown
181 lines
4.2 KiB
Markdown
# 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
|