From 857c3965efd72c1717d2e514abaefa195ab2d774 Mon Sep 17 00:00:00 2001 From: Scrublord MacBad Date: Thu, 14 May 2026 22:27:52 +0200 Subject: [PATCH] Add devcontainer for cross-platform development - Dockerfile with all required tools (kubectl, flux, helm, sops, age, etc.) - devcontainer.json with VSCode config and extensions - postCreateCommand.sh for setup verification - Comprehensive README with setup instructions for macOS, Windows/WSL2, Linux - Automatic mounts for kubeconfig, SSH keys, age encryption keys - SOPS_AGE_KEY_FILE and KUBECONFIG pre-configured Enables development on Windows, macOS, and Linux with consistent environment. Co-Authored-By: Claude Haiku 4.5 --- .devcontainer/Dockerfile | 56 ++++++++ .devcontainer/README.md | 203 +++++++++++++++++++++++++++++ .devcontainer/devcontainer.json | 47 +++++++ .devcontainer/postCreateCommand.sh | 35 +++++ 4 files changed, 341 insertions(+) create mode 100644 .devcontainer/Dockerfile create mode 100644 .devcontainer/README.md create mode 100644 .devcontainer/devcontainer.json create mode 100755 .devcontainer/postCreateCommand.sh diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..667776a --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,56 @@ +FROM debian:bookworm-slim + +# Install base tools +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + wget \ + git \ + ca-certificates \ + gnupg \ + lsb-release \ + apt-transport-https \ + vim \ + nano \ + jq \ + yq \ + zsh \ + sudo \ + openssh-client \ + && rm -rf /var/lib/apt/lists/* + +# Install kubectl +RUN curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg && \ + echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | tee /etc/apt/sources.list.d/kubernetes.list && \ + apt-get update && apt-get install -y kubectl && \ + rm -rf /var/lib/apt/lists/* + +# Install Helm +RUN curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash + +# Install Flux CLI +RUN curl -s https://fluxcd.io/install.sh | bash + +# Install sops +RUN SOPS_VERSION=$(curl -s https://api.github.com/repos/getsops/sops/releases/latest | grep tag_name | cut -d '"' -f 4) && \ + curl -sL -o /usr/local/bin/sops https://github.com/getsops/sops/releases/download/${SOPS_VERSION}/sops-${SOPS_VERSION}.linux.amd64 && \ + chmod +x /usr/local/bin/sops + +# Install age +RUN apt-get update && apt-get install -y age && \ + rm -rf /var/lib/apt/lists/* + +# Install Docker CLI (for interacting with Docker daemon) +RUN curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg && \ + echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \ + apt-get update && apt-get install -y docker-ce-cli && \ + rm -rf /var/lib/apt/lists/* + +# Create a non-root user 'vscode' for development +RUN useradd -m -s /bin/bash -G docker vscode && \ + echo "vscode ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers.d/vscode + +# Install oh-my-zsh for better shell experience +RUN su - vscode -c "sh -c '$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)' '' --unattended" + +USER vscode +WORKDIR /workspace diff --git a/.devcontainer/README.md b/.devcontainer/README.md new file mode 100644 index 0000000..466e2dc --- /dev/null +++ b/.devcontainer/README.md @@ -0,0 +1,203 @@ +# 🐳 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 ` 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` diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..01a7aee --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,47 @@ +{ + "name": "ESS Community GitOps", + "build": { + "dockerfile": "Dockerfile", + "context": "." + }, + "mounts": [ + "source=${localEnv:HOME}/.kube,target=/home/vscode/.kube,type=bind,consistency=cached", + "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached", + "source=${localEnv:HOME}/.age,target=/home/vscode/.age,type=bind,consistency=cached", + "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind" + ], + "remoteUser": "vscode", + "features": { + "ghcr.io/devcontainers/features/git:1": {}, + "ghcr.io/devcontainers/features/github-cli:1": {} + }, + "remoteEnv": { + "KUBECONFIG": "/home/vscode/.kube/config", + "SOPS_AGE_KEY_FILE": "/home/vscode/.age/keys.txt" + }, + "customizations": { + "vscode": { + "extensions": [ + "ms-kubernetes-tools.vscode-kubernetes-tools", + "redhat.vscode-yaml", + "redhat.vscode-commons", + "monokai.theme-monokai-pro-vscode", + "eamodio.gitlens" + ], + "settings": { + "[yaml]": { + "editor.defaultFormatter": "redhat.vscode-yaml", + "editor.formatOnSave": true, + "editor.tabSize": 2 + }, + "yaml.schemas": { + "https://json.schemastore.org/kustomization.json": "**/kustomization.yaml", + "https://json.schemastore.org/helmrelease.json": "**/*helmrelease*.yaml" + }, + "editor.theme": "Monokai Pro" + } + } + }, + "postCreateCommand": "bash .devcontainer/postCreateCommand.sh", + "forwardPorts": [] +} diff --git a/.devcontainer/postCreateCommand.sh b/.devcontainer/postCreateCommand.sh new file mode 100755 index 0000000..1dcee15 --- /dev/null +++ b/.devcontainer/postCreateCommand.sh @@ -0,0 +1,35 @@ +#!/bin/bash +set -e + +echo "🚀 Setting up ESS Community GitOps devcontainer..." + +# Verify all required tools are installed +echo "✅ Verifying installed tools..." +commands=("kubectl" "flux" "helm" "sops" "age" "git" "docker") + +for cmd in "${commands[@]}"; do + if command -v $cmd &> /dev/null; then + version=$($cmd version 2>/dev/null | head -1 || echo "installed") + echo " ✓ $cmd: $version" + else + echo " ✗ $cmd: NOT FOUND" + exit 1 + fi +done + +# Create necessary directories +echo "📁 Creating home directories..." +mkdir -p ~/.kube ~/.ssh ~/.age + +# Print useful information +echo "" +echo "📚 Useful commands:" +echo " - kubectl get pods -n matrix (check pod status)" +echo " - flux get helmreleases -A (check helm releases)" +echo " - sops apps/production/custom-configs/mas-secrets.sops.yaml (edit secrets)" +echo "" +echo "🔗 For kubeconfig setup:" +echo " - Copy your ~/.kube/config to access the cluster" +echo " - Run: kubectl get nodes" +echo "" +echo "✨ Devcontainer setup complete!"