JARVIS auf Unraid

Diese Anleitung beschreibt den spaeteren Docker-Start von JARVIS auf Unraid.

1. Finalen Stand auf Windows sichern

Vor dem Kopieren auf Unraid zuerst einen frischen Release-Stand mit ZIP erzeugen:

.\make-release.ps1 -Zip

Damit entsteht ein sauberer Stand im Ordner `releases/` und zusaetzlich eine ZIP-Datei. Der Release enthaelt keine `.venv`, keine Laufzeitdaten, keine Logs und keine Cache-Dateien.

2. Windows-Stand pruefen

Unter Windows sollte vor dem Kopieren der volle lokale Test laufen:

.\test-dev.ps1

Danach kann die Unraid-Konfiguration ohne Containerstart geprueft werden:

.\test-unraid-config.ps1

Erwartet:

Errors:   0

Eine Docker-Warnung ist auf Windows in Ordnung, wenn Docker dort nicht installiert oder nicht im PATH ist. Entscheidend ist, dass keine blockierenden Config-Fehler gemeldet werden.

3. Projekt auf Unraid ablegen

Der Inhalt des neuesten Release-Ordners oder der entpackten ZIP gehoert spaeter in einen persistenten Unraid-Pfad, zum Beispiel:

/mnt/user/appdata/JARVIS/Lokal-Jarvis

Wichtig sind diese Dateien und Ordner:

Dockerfile
docker-compose.yml
docker-compose.unraid.yml
config/
src/
requirements.txt
README.md
CHANGELOG.md

Nicht mitkopieren musst du `.venv`, alte `releases`, `logs`, `data` oder Python-Cache-Dateien. Der Ordner `data/` wird im Containerbetrieb automatisch fuer Sessions, Audit und Diagnose-Exporte genutzt.

Wenn Voice-Cloning aktiv ist, muss die Referenzstimme im persistenten Config-Volume liegen:

/mnt/user/appdata/JARVIS/config/voice/jarvis-reference.wav

Im Container muss dieselbe Datei unter `/app/config/voice/jarvis-reference.wav` sichtbar sein. Updates duerfen diese Datei nicht ueberschreiben oder entfernen.

Der Ordner `config/` muss im Container beschreibbar bleiben. Die Schnittstellen-Einstellungen legen dort Backups an und speichern bestaetigte Aenderungen in der aktiven YAML-Datei.

4. Unraid-Verzeichnis pruefen

Auf Unraid im Projektordner sollten diese Dateien direkt sichtbar sein:

ls -la

Erwartet sind mindestens:

Dockerfile
docker-compose.yml
docker-compose.unraid.yml
config/
src/
requirements.txt

5. Unraid-Start

Wenn der Projektordner aus einem privaten GitHub-Repository kommt, ist fuer Updates dieser Weg vorgesehen:

bash ./update-unraid.sh

Das Skript holt neue Dateien per Git, baut das JARVIS-Image neu, ersetzt nur den JARVIS-Container und laesst diese Betriebspfade unangetastet:

/mnt/user/appdata/JARVIS/config
/mnt/user/appdata/JARVIS/data
/mnt/user/appdata/JARVIS/logs

Standardmaessig veroeffentlicht es JARVIS auf Port `8002`, weil Port `8080` oft bereits von OmniVoice genutzt wird.

Nach einem Start mit `update-unraid.sh` kann das Dashboard selbst auf GitHub-Updates pruefen. Dafuer bindet das Skript den Projektordner nach `/app/source` und den Docker-Socket in den Container ein. Der Button funktioniert, wenn der Projektordner auf Unraid ein Git-Repository ist und `git pull` dort Zugriff auf dein privates GitHub-Repository hat.

Fuer dein Repository ist vorbereitet:

Repository: https://github.com/CryJacK21/Lokal-Jarvis
Branch:     main
Quelle:     /mnt/user/appdata/JARVIS/Lokal-Jarvis

GitHub-SSH auf Unraid einrichten

Auf Unraid in der Konsole:

mkdir -p /root/.ssh
chmod 700 /root/.ssh
ssh-keygen -t ed25519 -C "unraid-jarvis" -f /root/.ssh/jarvis_github
cat /root/.ssh/jarvis_github.pub

Den ausgegebenen Public Key in GitHub eintragen:

GitHub -> Settings -> SSH and GPG keys -> New SSH key

Danach auf Unraid die SSH-Konfiguration anlegen:

cat > /root/.ssh/config <<'EOF'
Host github.com
  HostName github.com
  User git
  IdentityFile /root/.ssh/jarvis_github
  IdentitiesOnly yes
EOF
chmod 600 /root/.ssh/config
ssh -T git@github.com

Wenn GitHub dich begruesst, den Projektordner klonen:

mkdir -p /mnt/user/appdata/JARVIS
cd /mnt/user/appdata/JARVIS
git clone git@github.com:CryJacK21/Lokal-Jarvis.git
cd Lokal-Jarvis
bash ./update-unraid.sh

Falls der Ordner schon existiert:

cd /mnt/user/appdata/JARVIS/Lokal-Jarvis
git remote set-url origin git@github.com:CryJacK21/Lokal-Jarvis.git
git fetch origin
git branch --set-upstream-to=origin/main main
bash ./update-unraid.sh

Bei Bedarf koennen Werte vor dem Start gesetzt werden:

JARVIS_HOST_PORT=8002 JARVIS_APPDATA_DIR=/mnt/user/appdata/JARVIS bash ./update-unraid.sh

Auf Unraid im Projektordner:

.\start-unraid.ps1 -CheckOnly

Das prueft Dateien, Unraid-Config, erwartete Ports und Docker Compose, ohne Container zu starten.

Danach starten:

.\start-unraid.ps1

Das startet den vorhandenen Docker-Stack ohne Neubau. Wenn nur Config-Werte geaendert wurden, reicht das normalerweise.

Wenn eine neue JARVIS-Version mit Code-Aenderungen eingespielt wurde:

.\start-unraid.ps1 -Build

Direkt mit Docker Compose entspricht das:

docker compose -f docker-compose.yml -f docker-compose.unraid.yml up -d

Dadurch wird fuer JARVIS automatisch diese Config verwendet:

config/config.unraid.yaml

6. Erwartete Dienste

Nach dem Start:

JARVIS Core:  http://UNRAID-IP:8002
Open WebUI:   http://UNRAID-IP:3000
Ollama API:   http://UNRAID-IP:11434

Open WebUI spricht JARVIS ueber die OpenAI-kompatible API an:

http://jarvis:8080/v1

JARVIS spricht Ollama im Docker-Netzwerk an:

http://ollama:11434

7. Nach dem Start pruefen

Im Browser:

http://UNRAID-IP:8080/
http://UNRAID-IP:8080/deployment/summary
http://UNRAID-IP:8080/unraid/readiness
http://UNRAID-IP:8080/open-webui/readiness
http://UNRAID-IP:8080/open-webui/selftest
http://UNRAID-IP:8080/config/validate
http://UNRAID-IP:8080/diagnostics/download

Im Dashboard sollten diese Kacheln auf `Bereit` stehen:

Deployment
Unraid
Open WebUI
Release-Pruefung
Alpha 0.1.0

8. Open WebUI pruefen

Open WebUI ist im Compose-Stack auf Port 3000 erreichbar:

http://UNRAID-IP:3000

Die interne API-Adresse fuer JARVIS lautet:

http://jarvis:8080/v1

Falls Open WebUI nach einem Modell fragt, sollte `jarvis` sichtbar sein. JARVIS routet dieses Modell intern auf das konfigurierte Ollama-Modell.

9. Diagnose sichern

Bei Problemen im Dashboard auf `Diagnose exportieren` klicken.

Alternativ:

http://UNRAID-IP:8080/diagnostics/download

Die Datei enthaelt Status, Config, Profile, Unraid-Readiness, Sessions, Audit und Metriken.

10. NVIDIA-Hinweis

Die Compose-Datei reserviert NVIDIA-GPU-Zugriff fuer Ollama. Auf Unraid muss die NVIDIA Runtime im System korrekt eingerichtet sein.

Wenn Ollama ohne GPU startet, ist JARVIS nicht automatisch defekt. Dann liegt das Problem wahrscheinlich in der Unraid-/Docker-GPU-Konfiguration.

11. Neustart nach Config-Aenderungen

Wenn spaeter Adressen oder Schnittstellenwerte geaendert werden, den Stack neu starten:

.\start-unraid.ps1

Nur nach Code-Aenderungen oder einem neuen Release-Stand neu bauen:

.\start-unraid.ps1 -Build

Direkt mit Docker Compose:

docker compose -f docker-compose.yml -f docker-compose.unraid.yml up -d

Wenn JARVIS manuell per `docker run` gestartet wird, den Config-Ordner ohne `:ro` einhaengen:

-v /mnt/user/appdata/JARVIS/config:/app/config

Eine Variante wie `/app/config:ro` blockiert das Speichern der Schnittstellen-Einstellungen.

Danach erneut pruefen:

http://UNRAID-IP:8080/deployment/summary