Major documentation restructure - consolidated docs
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
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>
This commit is contained in:
180
docs/wip/GITOPS-CONTAINERS.md
Normal file
180
docs/wip/GITOPS-CONTAINERS.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user