axion1337.chat-gitops/.devcontainer/README.md

# 🐳 DevContainer für ESS Community GitOps

Dieses DevContainer-Setup ermöglicht dir, auf **macOS, Windows und Linux** einheitlich zu entwickeln.

## 🚀 Schnelstart

### VSCode mit Remote Containers Extension

1. **VSCode Extension installieren:**
   - Öffne VSCode → Extensions → Suche nach `Dev Containers` (Microsoft)
   - Installiere sie

2. **GitOps Verzeichnis öffnen:**
   ```bash
   cd "april mit Ansible/prod/gitops"
   code .
   ```

3. **DevContainer starten:**
   - Klick auf `><` Symbol unten links in VSCode
   - Wähle `Reopen in Container`
   - Warte, bis das Image gebaut wurde (~3-5 Min beim ersten Mal)

### Alternative: Docker + CLI

```bash
docker build -t ess-gitops .devcontainer
docker run -it --rm \
  -v ~/.kube:/home/vscode/.kube \
  -v ~/.ssh:/home/vscode/.ssh \
  -v ~/.age:/home/vscode/.age \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ess-gitops
```

## 📦 Enthaltene Tools

- **kubectl** - Kubernetes CLI
- **flux** - FluxCD GitOps Controller CLI
- **helm** - Kubernetes Package Manager
- **sops** - Secret Operations (Verschlüsselung)
- **age** - Modern File Encryption
- **docker** - Container CLI (über Host-Socket)
- **git** - Versionskontrolle
- **jq/yq** - JSON/YAML Processing
- **zsh + oh-my-zsh** - Shell mit Plugins

## 🔐 Wichtige Verzeichnis-Binds

Der Container mountet automatisch:

| Host | Container | Zweck |
|------|-----------|-------|
| `~/.kube` | `/home/vscode/.kube` | Kubernetes Config |
| `~/.ssh` | `/home/vscode/.ssh` | SSH Keys |
| `~/.age` | `/home/vscode/.age` | Age Encryption Keys |
| `/var/run/docker.sock` | `/var/run/docker.sock` | Docker Daemon (für `docker` Befehle) |

## ⚙️ Kubeconfig Einrichten

1. **Host-Machine (z.B. macOS):**
   ```bash
   # Stelle sicher, dass ~/.kube/config existiert und den richtigen Cluster enthält
   kubectl get nodes
   ```

2. **Im Container:**
   ```bash
   kubectl get nodes  # Sollte jetzt auch dein Cluster zeigen
   kubectl config current-context
   ```

## 🔐 SOPS + Age Setup

Damit du Secrets bearbeiten kannst, brauchst du den privaten `age`-Key. Dieser ist in `.sops.yaml` konfiguriert.

### Schritt 1: Age-Key bereitstellen

```bash
# Host-Machine: Key-Datei erstellen
mkdir -p ~/.age
# Füge deinen privaten Key ein (Format: "age-secret-key-...")
echo "age-secret-key-xxx..." > ~/.age/keys.txt
chmod 600 ~/.age/keys.txt
```

### Schritt 2: Im Container konfigurieren

Der Container mounted `~/.age` automatisch. Setze die Umgebungsvariable:

```bash
# Im Container-Terminal (SOPS_AGE_KEY_FILE ist bereits automatisch gesetzt!)
# Jetzt kannst du Secrets bearbeiten (wird transparent ver-/entschlüsselt):
sops apps/production/custom-configs/mas-secrets.sops.yaml
```

### Schritt 3: VSCode Integration (optional)

Um die Umgebungsvariable beim Start zu setzen, nutze die `.devcontainer/devcontainer.json`:

```json
"remoteEnv": {
  "KUBECONFIG": "/home/vscode/.kube/config",
  "SOPS_AGE_KEY_FILE": "/home/vscode/.age/keys.txt"
}
```

### Wie es funktioniert

- `.sops.yaml` definiert, dass Secrets mit `age` verschlüsselt werden
- Beim Öffnen mit `sops <datei>` wird die Datei entschlüsselt → du editierst den plaintext in deinem Editor
- Beim Speichern wird alles wieder automatisch verschlüsselt
- **Wichtig:** Niemals den plaintext-Buffer commiten!

## 📝 Nach Container-Start: Git Hooks Installieren

Wichtig für die ConfigMap Auto-Sync (verhindert Merge-Konflikte):

```bash
./scripts/install-hooks.sh
```

Mehr Details: `docs/ops-configmap-sync.md`

## 📝 Nützliche Befehle

```bash
# Status des Deployments
kubectl get pods -n matrix
flux get helmreleases -A

# Secrets bearbeiten (mit verschlüsselung)
sops apps/production/custom-configs/mas-secrets.sops.yaml

# FluxCD Sync erzwingen
flux reconcile kustomization production-apps --with-source

# Zertifikate debuggen
kubectl get certificate -n matrix
kubectl describe certificate matrix-ingress -n matrix

# HelmRelease Status prüfen
flux describe helmrelease matrix-stack -n matrix
```

## 🛠️ Anpassungen für Windows/WSL2

Falls du Windows nutzt:

1. **Docker Desktop installieren** (mit WSL2 Backend)
2. **VSCode mit WSL Extension öffnen**
3. **Im WSL Terminal:**
   ```bash
   cd /mnt/c/path/to/projekt
   code .
   ```
4. Dann `Dev Containers: Reopen in Container`

Das funktioniert seamless, weil Docker Desktop unter WSL2 läuft.

## 🔧 Troubleshooting

### Problem: `SOPS_AGE_KEY_FILE not found`
**Lösung:** Key muss in `~/.age/keys.txt` auf der Host-Machine sein:
```bash
# Host
mkdir -p ~/.age
echo "your-age-private-key" > ~/.age/keys.txt
```
Der Container mountet `~/.age` automatisch → sollte dann funktionieren.

### Problem: `kubectl: connection refused`
**Lösung:** `~/.kube/config` muss auf Host vorhanden sein:
```bash
# Host
kubectl get nodes  # Test, ob Zugriff existiert
# Dann Container neustarten
```

### Problem: `HelmChart is not ready: stat ... no such file or directory`
Siehe `README.md` → **Issue 1**. Kontrolliere:
- `HelmRepository` nutzt `type: oci`
- URL ist `oci://ghcr.io/element-hq/ess-helm`

### Problem: `values don't meet the specifications of the schema`
Siehe `README.md` → **Issue 2**. Häufige Fehler:
- `tls:` darf nicht im `ingress:` Block sein
- `serverName` muss auf Root-Ebene der `values` stehen
- Komponenten-Namen: `camelCase` (z.B. `elementWeb`, `matrixAuthenticationService`)

### Problem: Let's Encrypt `403 Order's status is processing`
Siehe `README.md` → **Issue 3**. Kurz: 
- `wellKnownDelegation: enabled: false` setzen
- Oder `.well-known/matrix/server` manuell auf `elementWeb` weiterleiten

## 📚 Weitere Ressourcen

- [Dev Containers Docs](https://containers.dev)
- [FluxCD Dokumentation](https://fluxcd.io)
- [SOPS Anleitung](https://github.com/getsops/sops)
- **Projekt-README:** `README.md` (Architektur, Issues, Best Practices)
- **Setup-Docs:** `docs/setup/`
- **Install-Guide:** `docs/install.md`