Neue Dokumentationsdateien
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 6s
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 6s
This commit is contained in:
parent
882ae5368f
commit
9e7104e362
3
.vscode/settings.json
vendored
Normal file
3
.vscode/settings.json
vendored
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
{
|
||||
"CodeGPT.apiKey": "Google AI Studio"
|
||||
}
|
||||
143
docs/dev_workflow.md
Normal file
143
docs/dev_workflow.md
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
# Mindnet v2.2 – Entwickler-Workflow
|
||||
**Datei:** `DEV_WORKFLOW.md`
|
||||
**Stand:** 2025-12-07
|
||||
|
||||
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 trennen strikt:
|
||||
* **PROD (`~/mindnet`):** Läuft stabil auf `main`. **Port 8001**.
|
||||
* **DEV (`~/mindnet_dev`):** Deine Spielwiese für Branches. **Port 8002**.
|
||||
|
||||
---
|
||||
|
||||
## 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. **Sicherstellen, dass Git bereit ist:**
|
||||
* Öffne VS Code.
|
||||
* Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
|
||||
|
||||
2. **Branch erstellen (WICHTIG):**
|
||||
* Klicke unten links auf den Branch-Namen (z.B. `main`).
|
||||
* Wähle im Menü oben `+ Create new branch...`.
|
||||
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
|
||||
* Drücke **Enter**.
|
||||
|
||||
3. **Sicherheits-Check:**
|
||||
* Schau unten links: Steht dort jetzt `feature/wp04b-explanation`?
|
||||
* **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch.
|
||||
|
||||
4. **Coden:**
|
||||
* Nimm deine Änderungen vor.
|
||||
|
||||
5. **Sichern & Hochladen:**
|
||||
* Klicke links auf das **Source Control** Icon (Gabel-Symbol).
|
||||
* Gib eine Nachricht ein: "feat: Add explanation layer logic".
|
||||
* Klicke auf **Commit**.
|
||||
* Klicke auf **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, ohne die Produktion zu stören.
|
||||
|
||||
1. **Einloggen:**
|
||||
`ssh user@<BEELINK-IP>`
|
||||
|
||||
2. **In die Werkstatt gehen:**
|
||||
`cd /home/llmadmin/mindnet_dev`
|
||||
|
||||
3. **Code holen:**
|
||||
```bash
|
||||
git fetch
|
||||
git checkout feature/wp04b-explanation
|
||||
git pull
|
||||
```
|
||||
|
||||
4. **Umgebung aktivieren (Venv):**
|
||||
Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
*(Dein Prompt sollte jetzt `(.venv) user@...` zeigen)*
|
||||
|
||||
5. **Abhängigkeiten prüfen:**
|
||||
*(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)*
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
6. **Test-Server starten:**
|
||||
**WICHTIG:** Nutze Port **8002** und das Dev-Prefix!
|
||||
Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`.
|
||||
|
||||
```bash
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8002
|
||||
```
|
||||
|
||||
7. **Testen:**
|
||||
Prüfe deine Änderung (z.B. Browser auf `http://<BEELINK-IP>:8002/docs` oder Smoke-Test Skript).
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Release (Gitea / Raspberry Pi)
|
||||
|
||||
Wenn der Test auf Port 8002 erfolgreich war:
|
||||
|
||||
1. Öffne Gitea im Browser.
|
||||
2. Du solltest einen Hinweis sehen "feature/... had recent pushes".
|
||||
3. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
||||
4. **Merge** den Pull Request.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Deployment (Beelink / `mindnet`)
|
||||
|
||||
Jetzt bringen wir die Änderung in das Live-System (Port 8001).
|
||||
|
||||
1. **Deploy-Agent (Automatisch):**
|
||||
Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!
|
||||
|
||||
2. **Manuell (Falls nötig):**
|
||||
```bash
|
||||
cd /home/llmadmin/mindnet
|
||||
git pull origin main
|
||||
sudo systemctl restart mindnet-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Cheat Sheet: Die wichtigsten Befehle
|
||||
|
||||
| Wo? | Befehl | Was tut es? |
|
||||
| :--- | :--- | :--- |
|
||||
| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
|
||||
| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
|
||||
| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
|
||||
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
|
||||
| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" |
|
||||
| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
|
||||
| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. |
|
||||
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
|
||||
|
||||
---
|
||||
|
||||
## 4. Sicherheitsregeln
|
||||
|
||||
1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. Dieser Ordner bleibt immer auf `main`.
|
||||
2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
|
||||
* Prod `.env`: `COLLECTION_PREFIX="mindnet"`
|
||||
* Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`
|
||||
3. **Port-Disziplin:**
|
||||
* **PROD:** Port 8001
|
||||
* **DEV:** Port 8002
|
||||
Loading…
Reference in New Issue
Block a user