Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
8afa402118
mindnet/docs/dev_workflow.md
Lars 8afa402118
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Details
docs/dev_workflow.md aktualisiert
2025-12-13 10:09:05 +01:00

7.4 KiB
Raw Blame History

Mindnet v2.4 – Entwickler-Workflow

Datei: docs/DEV_WORKFLOW.md Stand: 2025-12-12 (Aktualisiert: v2.6 mit Traffic Control)

Dieses Handbuch beschreibt den Entwicklungszyklus zwischen Windows PC (IDE), Raspberry Pi (Gitea) und Beelink (Runtime/Server).

1. Die Architektur

  • 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 nutzen Systemd-Services:
    • PROD:
      • API: mindnet-prod (Port 8001). Ordner: ~/mindnet.
      • UI: mindnet-ui-prod (Port 8501).
    • DEV:
      • API: mindnet-dev (Port 8002). Ordner: ~/mindnet_dev.
      • UI: mindnet-ui-dev (Port 8502).

2. Der Zyklus: Von der Idee zum Release

Phase 1: Entwicklung (Windows / VS Code)

Hier erstellst du die neue Funktion in einer sicheren Umgebung.

  1. Basis aktualisieren (WICHTIG!): Bevor du startest, muss dein lokales main auf dem Stand des Servers sein.

    • Klicke unten links auf den aktuellen Branch und wähle main.
    • Klicke links im Menü "Source Control" auf die drei Punkte (...) -> Pull (oder das Synchronisieren-Symbol).
    • Erst jetzt hast du alle Dateien!

  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/wp15-traffic-control).
    • Drücke Enter.

  3. Sicherheits-Check:

    • Steht unten links jetzt dein Feature-Branch? Nur dann darfst du Code ändern!

  4. Coden:

    • Nimm deine Änderungen vor (z.B. neue Schemas in types.yaml oder Async-Logik in ingestion.py).

  5. Sichern & Hochladen:

    • Source Control Icon (Gabel-Symbol) -> Nachricht eingeben -> Commit.
    • Publish Branch (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.

Phase 2: Testen (Beelink / mindnet_dev)

Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.

  1. Einloggen: ssh user@<BEELINK-IP>

  2. In die Werkstatt gehen: cd /home/llmadmin/mindnet_dev

  3. Code holen:

    git fetch
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
git checkout feature/wp15-traffic-control
git pull

  4. Umgebung vorbereiten (WICHTIG für v2.6): Prüfe deine .env Datei. Sie benötigt jetzt Einträge für die Traffic Control.

    nano .env

    Ergänze/Prüfe:

    # Traffic Control (Neu in v2.6)
MINDNET_LLM_BACKGROUND_LIMIT=2  # Max. parallele Import-Tasks
MINDNET_API_TIMEOUT=300.0       # Frontend wartet länger
MINDNET_EMBEDDING_MODEL="nomic-embed-text"

    Dependencies aktualisieren:

    source .venv/bin/activate
pip install -r requirements.txt
ollama pull nomic-embed-text

  5. Test-Server aktualisieren (WICHTIG): Der Code ist da, aber die Prozesse im RAM sind noch alt. Wir müssen die Services neustarten.

    Option A: Standard (Als Service laufen lassen) Ideal, wenn du nur testen willst, ob es läuft.

    # 1. API neustarten (Backend)
sudo systemctl restart mindnet-dev
# 2. UI neustarten (Frontend)
sudo systemctl restart mindnet-ui-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.

    # 1. Services stoppen (wichtig, sonst sind Ports 8002/8502 belegt!)
sudo systemctl stop mindnet-dev
sudo systemctl stop mindnet-ui-dev

# 2. Manuell starten (z.B. API)
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env

  6. Validieren (Smoke Tests v2.6):

    • Test A: Last-Test (Traffic Control):

      1. Starte einen Import im Terminal: python3 -m scripts.import_markdown ...
      2. Öffne gleichzeitig http://<IP>:8502 im Browser.
      3. Stelle eine Chat-Frage ("Was ist Mindnet?").
      4. Erwartung: Der Chat antwortet sofort (Realtime Lane), während der Import im Hintergrund weiterläuft (Background Lane).

    • Test B: API Check

      curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'

Phase 3: Release (Gitea / Raspberry Pi)

Wenn der Test auf Port 8002 / 8502 erfolgreich war:

  1. Öffne Gitea im Browser.
  2. Erstelle einen Pull Request (Dein Branch -> main).
  3. Merge den Pull Request.

Phase 4: Deployment (Beelink / mindnet)

Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501).

  1. Deploy-Agent (Automatisch): Wenn dein deploy.yml aktiv ist, passiert das jetzt von selbst!

  2. Manuell (Falls nötig):

    cd /home/llmadmin/mindnet
git pull origin main

# Dependencies updaten & Modelle checken
source .venv/bin/activate
pip install -r requirements.txt
ollama pull nomic-embed-text

# .env prüfen (Traffic Control)
# Ggf. MINDNET_LLM_BACKGROUND_LIMIT=2 hinzufügen

# Falls sich die Vektor-Dimension geändert hat (v2.4 Upgrade):
# python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force

# Produktions-Services neustarten
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod

Phase 5: Aufräumen (Optional aber empfohlen)

Damit das Chaos nicht wächst, löschen wir den fertigen Branch.

  1. Gitea: Im Pull Request auf "Delete Branch" klicken.
  2. Beelink (Dev): 
    cd ~/mindnet_dev
git checkout main
git pull
git branch -d feature/wp15-traffic-control
  3. VS Code:
    • Auf main wechseln.
    • Sync drücken.
    • F1 -> Git: Delete Branch -> Branch auswählen.

3. Cheat Sheet: Die wichtigsten Befehle

Wo? Befehl Was tut es?
Beelink sudo systemctl restart mindnet-dev Neustart Dev-Backend (Port 8002).
Beelink sudo systemctl restart mindnet-ui-dev Neustart Dev-Frontend (Port 8002).
Beelink journalctl -u mindnet-dev -f Live-Logs Backend.
Beelink python debug_analysis.py Prüft Aliases & Scores.
Beelink python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes Löscht & Repariert DB.
Beelink python3 -m scripts.import_markdown --vault ./vault_master --prefix "mindnet" --apply --force Löscht & Repariert DB.
Beelink source .venv/bin/activate Aktivieren des virtual environments

4. Troubleshooting

"Read timed out" im Frontend

  • Ursache: Backend braucht für Smart Edges länger als 60s.
  • Lösung: MINDNET_API_TIMEOUT=300.0 in .env setzen und Services neustarten.

Import ist extrem langsam

  • Ursache: Smart Edges analysieren jeden Chunk mit LLM.
  • Lösung:
    • Akzeptieren (Qualität vor Speed).
    • Oder temporär in config/types.yaml: enable_smart_edge_allocation: false.

"UnicodeDecodeError in .env"

  • Ursache: Umlaute oder Sonderzeichen in der .env Datei.
  • Lösung: .env bereinigen (nur ASCII nutzen) und sicherstellen, dass sie UTF-8 ohne BOM ist.