From 18c9ce87548cb9a5190f32ff1b227c6d24170fbe Mon Sep 17 00:00:00 2001 From: Floke Date: Tue, 10 Mar 2026 19:14:38 +0000 Subject: [PATCH] [30388f42] docs: add UMZUG Live Lessons Learned to RELOCATION.md --- RELOCATION.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/RELOCATION.md b/RELOCATION.md index 3daadc8e..0b20d950 100644 --- a/RELOCATION.md +++ b/RELOCATION.md @@ -337,3 +337,42 @@ Das neue Gitea (auf Port 3000) wird zur zentralen "Source of Truth". Dieser Prozess ist sicher, schnell und wiederholbar, da er nur aus Standard-Git- und Docker-Befehlen besteht. +--- + +### **UMZUG Live - Lessons Learned (März 2026)** + +Der reale Umzug von der Synology auf die Wackler-VM (`docker1`) hat gezeigt, dass die Theorie gut war, die Praxis aber spezifische Hürden bereithielt. Diese Lektionen sind kritisch für alle zukünftigen Deployments: + +#### **1. Die Git-Historien-Falle (Packfile / Timeout Error)** +* **Problem:** Versuche, das Repository per `git clone` oder über die Gitea-Migrations-Funktion umzuziehen, brachen reproduzierbar mit `RPC failed; HTTP 504` oder `fatal: expected 'packfile'` ab. +* **Ursache:** Das lokale `.git` Verzeichnis war auf **1,4 Gigabyte** angewachsen, da in der Vergangenheit versehentlich große MP3-Dateien committet wurden. Auch nach dem Löschen verbleiben diese in der Historie und blockieren den Transfer über Proxies. +* **Lösung:** Radikale Bereinigung der Historie via `git filter-branch` (oder `git filter-repo`) für den Ordner `uploads_audio/`, gefolgt von einer aggressiven Garbage Collection (`git gc --prune=now --aggressive`). +* **Ergebnis:** Schrumpfung des Repos von 1,4 GB auf **130 MB**. +* **Lesson:** Bei Git-Transfer-Fehlern zuerst die Größe des `.git` Ordners prüfen. + +#### **2. Der "Filter-Branch" Nebeneffekt (.env Schutz)** +* **Problem:** Nach der Git-Bereinigung schienen ungetrackte Dateien (wie `.env` und `volume_backups/`) plötzlich verschwunden. +* **Ursache:** `git filter-branch` erzwingt einen harten Reset auf den bereinigten Stand. Dateien, die in der `.gitignore` stehen, werden dabei oft aus dem Arbeitsverzeichnis entfernt. +* **Lösung:** Wiederherstellung aus einem zuvor erstellten `.tar.gz`-Backup des gesamten Projektverzeichnisses. +* **Lesson:** Führe niemals tiefe Git-Eingriffe ohne ein physisches Dateibackup der ungetrackten Dateien durch. + +#### **3. Das "Transit-Repo" Muster für Secrets** +* **Problem:** Sicherer Transfer der `.env` und Datenbanken ohne Einchecken in das Haupt-Repo und ohne Zugriff auf externe Transfer-Dienste (Firewall-Blockade). +* **Lösung:** Erstellung eines temporären, privaten Gitea-Repositorys namens `transit` auf dem Ziel-System. Hochladen des verschlüsselten Backups über die Gitea-Weboberfläche und anschließendes Klonen/Entpacken auf der VM. Danach sofortige Löschung des `transit` Repos. +* **Lesson:** Gitea ist das beste Transit-Medium für große Files hinter restriktiven Firewalls. + +#### **4. Docker Build Context & Berechtigungen** +* **Problem:** `docker compose up --build` brach ab mit: `failed to solve: error from sender: open /volume_backups: permission denied`. +* **Ursache:** Docker versucht beim Bauen das gesamte Verzeichnis einzulesen. Ordner, die dem `root` User gehören (z.B. durch Gemini-Aktionen erstellt), blockieren den Prozess. +* **Lösung:** + 1. Berechtigungen korrigieren: `sudo chown -R $USER:$USER volume_backups/` + 2. Ordner in der `.dockerignore` ausschließen, damit er gar nicht erst eingelesen wird. +* **Lesson:** Alles, was nicht in ein Container-Image gehört, **muss** in die `.dockerignore`. + +#### **5. Vite & TypeScript Build-Tücken** +* **Problem:** Der Frontend-Build schlug fehl, weil die `tsconfig.json` im Container nicht gefunden wurde. +* **Ursache:** `COPY . .` verhält sich in komplexen Verzeichnisstrukturen manchmal unvorhersehbar. +* **Lösung:** Explizites Kopieren aller Konfigurationsdateien im Dockerfile: `COPY tsconfig.json tsconfig.node.json tsconfig.app.json vite.config.ts ./` direkt vor dem Build-Schritt. +* **Lesson:** Verlasse dich beim Build nicht auf Wildcards; kopiere essenzielle Config-Files explizit. + +