diff --git a/docs/dev_workflow.md b/docs/dev_workflow.md index 01af4c8..6d1cf9d 100644 --- a/docs/dev_workflow.md +++ b/docs/dev_workflow.md @@ -1,6 +1,6 @@ # Mindnet v2.2 – Entwickler-Workflow **Datei:** `DEV_WORKFLOW.md` -**Stand:** 2025-12-07 (Aktualisiert: Sync-First Strategie) +**Stand:** 2025-12-08 (Aktualisiert: Systemd Services & Sync-First) Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server). @@ -10,9 +10,9 @@ Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), * **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten! * **Raspberry Pi (Gitea):** Der Tresor. Speichert den Code und verwaltet Versionen. -* **Beelink (Runtime):** Hier läuft die Software. Wir trennen strikt: - * **PROD (`~/mindnet`):** Läuft stabil auf `main`. **Port 8001**. - * **DEV (`~/mindnet_dev`):** Deine Spielwiese für Branches. **Port 8002**. +* **Beelink (Runtime):** Hier läuft die Software. Wir nutzen **Systemd-Services**: + * **PROD (`mindnet-prod`):** Läuft stabil auf `main`. Ordner: `~/mindnet`. **Port 8001**. + * **DEV (`mindnet-dev`):** Deine Spielwiese. Ordner: `~/mindnet_dev`. **Port 8002**. --- @@ -31,7 +31,7 @@ Hier erstellst du die neue Funktion in einer sicheren Umgebung. 2. **Branch erstellen:** * Klicke wieder unten links auf `main`. * Wähle `+ Create new branch...`. - * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`). + * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp05-chat`). * Drücke **Enter**. 3. **Sicherheits-Check:** @@ -60,31 +60,49 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft. ```bash git fetch # Tipp: 'git branch -r' zeigt alle verfügbaren Branches an - git checkout feature/wp04b-explanation + git checkout feature/wp05-chat git pull ``` -4. **Umgebung vorbereiten:** +4. **Umgebung vorbereiten (bei Bedarf):** ```bash source .venv/bin/activate pip install -r requirements.txt # Nur nötig bei neuen Paketen ``` -5. **Test-Server neustarten (WICHTIG):** - Falls noch ein alter Prozess läuft, musst du ihn beenden. - * Drücke `Strg + C` falls der Server noch im Vordergrund läuft. - * Oder nutze `pkill -f "uvicorn app.main:app"`. +5. **Test-Server aktualisieren (WICHTIG):** + Der Code ist da, aber der Prozess im RAM ist noch alt. Wir müssen den Service neustarten. - Starten auf **Port 8002**: + **Option A: Standard (Als Service laufen lassen)** + Ideal, wenn du nur testen willst, ob es läuft. ```bash + sudo systemctl restart mindnet-dev + + # Logs prüfen (um Fehler zu sehen): + journalctl -u mindnet-dev -f + ``` + + **Option B: Manuell Debuggen (Direct Output)** + Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht. + ```bash + # 1. Service stoppen (wichtig, sonst ist Port 8002 belegt!) + sudo systemctl stop mindnet-dev + + # 2. Manuell starten uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env + + # ... Testen ... + + # 3. Wenn fertig: Service wieder anschalten (Optional) + # Strg+C drücken + sudo systemctl start mindnet-dev ``` 6. **Validieren:** Führe deine Tests in einem **zweiten Terminal** aus: ```bash # Beispiel für Smoke-Test gegen Dev-Port - python3 tests/test_explanation_smoke.py --url http://localhost:8002/query + python3 tests/test_chat_smoke.py --url http://localhost:8002/chat ``` --- @@ -110,7 +128,12 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001). ```bash cd /home/llmadmin/mindnet git pull origin main - sudo systemctl restart mindnet-api + + # Produktions-Service neustarten + sudo systemctl restart mindnet-prod + + # Kurz prüfen, ob er läuft + sudo systemctl status mindnet-prod ``` --- @@ -125,11 +148,12 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch. cd ~/mindnet_dev git checkout main git pull - git branch -d feature/wp04b-explanation + git branch -d feature/wp05-chat ``` + *Hinweis: Der `mindnet-dev` Service läuft jetzt mit dem Code von `main`, was okay ist.* 3. **VS Code:** * Auf `main` wechseln. - * Sync drücken (um Löschung vom Server zu erfahren). + * Sync drücken. * `F1` -> `Git: Delete Branch` -> Branch auswählen. --- @@ -139,22 +163,25 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch. | Wo? | Befehl | Was tut es? | | :--- | :--- | :--- | | **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. | -| **VS Code** | `Klick auf Branch` | Branch erstellen oder wechseln. | -| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** | -| **Beelink** | `git fetch` | Aktualisiert Remote-Branches. | +| **Beelink** | `git fetch` | Aktualisiert Liste der Remote-Branches. | | **Beelink** | `git checkout ` | Wechsle Branch. | | **Beelink** | `git pull` | Aktualisiere aktuellen Branch. | -| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). | +| **Beelink** | `sudo systemctl restart mindnet-dev` | **Neustart Dev-Server (Port 8002).** | +| **Beelink** | `sudo systemctl stop mindnet-dev` | **Stoppt Dev-Server (macht Port frei).** | +| **Beelink** | `sudo systemctl restart mindnet-prod`| **Neustart Prod-Server (Port 8001).** | +| **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs vom Dev-Server sehen.** | --- ## 4. Troubleshooting +**"Port 8002 already in use"** +* Du willst `uvicorn` manuell starten, aber der Service läuft noch. +* **Lösung:** `sudo systemctl stop mindnet-dev` + **"Hilfe, in meinem neuen Branch fehlen Dateien!"** -Das passiert, wenn du beim Erstellen nicht aktuell warst. +* Das passiert, wenn du beim Erstellen nicht aktuell warst. * **Lösung:** ```bash - # In VS Code Terminal: git checkout feature/mein-kaputter-branch - git merge main - # (Das holt die fehlenden Dateien aus main nach) \ No newline at end of file + git merge main \ No newline at end of file