InfraQuill – Installationsanleitung

InfraQuill ist eine KI-gestützte Netzwerk-Dokumentationsanwendung. Sie läuft vollständig via Docker und benötigt keine Cloud-Verbindung (Ollama lokal).

---

Voraussetzungen

| Anforderung | Details | |---|---| | Docker | ≥ 24.x | | Docker Compose | ≥ v2 (Plugin docker compose, nicht docker-compose) | | Python 3 | Für manage.sh (Update-Logik) | | RAM | Mindestens 4 GB (Ollama-Modell: ca. 5–6 GB empfohlen) | | Speicherplatz | Mindestens 10 GB (Ollama-Modell + Daten) |

Systemunterstützung

• Linux (Ubuntu 22.04+, Debian 11+, Rocky/AlmaLinux 9)
• UGREEN NAS (DXP- und NASync-Serie mit Docker-Unterstützung)
• Synology NAS (DSM 7.2+, Container Manager)
• Unraid (Docker-Plugin aktiv)
• Proxmox LXC (mit Docker installiert)
• Raspberry Pi 4/5 (64-bit OS, kein GPU-Support)
• Windows (via WSL2 + Docker Desktop, WSL-Integration aktiviert)
• macOS (mit Docker Desktop)

manage.sh ist ein POSIX-sh-Skript und benötigt Python 3 sowie docker compose. Unter Windows läuft es nur innerhalb von WSL2 (nicht in PowerShell/cmd) – Docker Desktop muss dort die WSL-Integration für die genutzte Distribution aktiviert haben.

---

Verzeichnisstruktur nach Installation

infraquill/                     ← Installationsordner
├── manage.sh                   ← Management-Skript
├── docker-compose.yml          ← aus .example angelegt (beim ersten Update)
├── docker-compose.yml.example  ← Vorlage (nie manuell anpassen!)
├── .env                        ← aus .example angelegt (beim ersten Update)
├── .env.example                ← Vorlage
├── data/                       ← persistente Daten (wird nie überschrieben)
│   └── ollama/                 ← Ollama-Modelle
└── logs/
    └── deploy.log              ← Update-Protokoll

---

Neue Installation (Erst-Setup)

Schritt 1 – Installationsordner erstellen

Empfohlener Pfad je System:

| System | Empfohlener Pfad | |---|---| | Linux-Server / Proxmox LXC | /opt/infraquill | | UGREEN NAS (UGOS Pro) | /volume1/docker/infraquill | | Synology NAS (DSM) | /volume1/docker/infraquill | | Unraid | /mnt/user/appdata/infraquill | | Raspberry Pi | /opt/infraquill (oder /home/pi/infraquill) | | Windows (in WSL2!) | z. B. ~/infraquill innerhalb der WSL-Distribution | | macOS | ~/infraquill |

Der genaue Pfad hängt vom Datenvolume ab (bei UGREEN/Synology per Datei-Manager/Volume-Übersicht prüfen, welches Volume für Docker-Daten vorgesehen ist).

mkdir -p /opt/infraquill
cd /opt/infraquill

UGREEN/Synology NAS: Am einfachsten per SSH auf dem NAS ausführen, alternativ per Datei-Manager den Ordner anlegen und danach per SSH in den Ordner wechseln (SSH wird für manage.sh benötigt). Windows: Zuerst WSL2-Terminal öffnen (wsl in PowerShell), dann die Befehle innerhalb von WSL ausführen – nicht in PowerShell/cmd.

Schritt 2 – Dateien ablegen

Die infraquill_release.zip und manage.sh in den Installationsordner kopieren.

/opt/infraquill/
├── infraquill_release.zip
└── manage.sh

Schritt 3 – manage.sh ausführbar machen

chmod +x manage.sh

Schritt 4 – Erstes Update / Installation

./manage.sh update

Das Skript:

1. Entpackt die ZIP (via Python 3, kein unzip nötig)
2. Legt docker-compose.yml aus der .example-Vorlage an
3. Legt .env aus der .example-Vorlage an
4. Baut die Docker-Images und startet die Container

Schritt 5 – Konfiguration anpassen

Die .env anpassen:

nano .env

Wichtige Werte:

# KI-Backend: "ollama" (lokal, kein API-Key) oder "anthropic"/"openai" (Cloud)
AI_BACKEND=ollama

# Ollama läuft im selben Docker-Netzwerk
OLLAMA_URL=http://ollama:11434
OLLAMA_MODEL=qwen2.5vl:7b

# API-Keys (nur wenn Cloud-Backend gewünscht)
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

# Sicherheitsschlüssel – unbedingt ändern!
SECRET_KEY=changeme-set-random-value

# Speicherpfad für Ollama-Modelle
# Standard: ./data/ollama
# NAS-Empfehlung: absoluter Pfad auf das Daten-Volume
OLLAMA_MODELS_PATH=./data/ollama

Wichtig: SECRET_KEY muss ein langer zufälliger Wert sein. Generierung:

> python3 -c "import secrets; print(secrets.token_hex(32))"
> 

Schritt 6 – Container neu starten (nach Konfigurationsänderung)

./manage.sh restart

---

Erreichbarkeit

| Dienst | URL | |---|---| | InfraQuill Web-UI | http://<IP-Adresse>:5743 | | Ollama API (intern) | http://localhost:11434 |

---

GPU-Unterstützung (optional)

NVIDIA

1. NVIDIA Container Toolkit installieren
2. In docker-compose.yml den deploy-Block beim ollama-Service einkommentieren

AMD ROCm

1. Image in docker-compose.yml ändern: ollama/ollama:rocm
2. devices-Block für /dev/kfd und /dev/dri einkommentieren

---

Update (bestehende Installation)

1. Neue infraquill_release.zip in den Installationsordner legen
2. Update starten:

./manage.sh update

Was passiert beim Update:

• Code-Dateien werden aktualisiert
• docker-compose.yml und .env bleiben unverändert (werden nicht überschrieben)
• data/-Ordner wird nicht berührt (Ollama-Modelle bleiben erhalten)
• Docker-Images werden neu gebaut und Container werden neu gestartet
• Die ZIP wird nach dem Update umbenannt (als Archiv)

---

Watch-Modus (automatische Updates)

Der Watch-Modus prüft alle 30 Sekunden, ob eine neue infraquill_release.zip vorhanden ist, und deployt sie automatisch.

./manage.sh watch

Nützlich für automatisierte Deployments via SFTP/SCP auf NAS-Systemen.

Zum Starten als Hintergrunddienst:

nohup ./manage.sh watch > logs/watch.log 2>&1 &

---

manage.sh – Alle Befehle

./manage.sh update          # Update aus infraquill_release.zip
./manage.sh update datei.zip # Update aus bestimmter ZIP
./manage.sh watch           # Watch-Modus: neue ZIP → auto deploy
./manage.sh start           # Container starten
./manage.sh stop            # Container stoppen
./manage.sh restart         # Container neu starten
./manage.sh status          # Container-Status anzeigen
./manage.sh logs            # Alle Logs (live)
./manage.sh logs infraquill # Logs eines bestimmten Dienstes

---

Fehlerbehebung

Container starten nicht

./manage.sh logs
# oder gezielt:
./manage.sh logs infraquill
./manage.sh logs ollama

Ollama-Modell fehlt / wird nicht geladen

./manage.sh logs ollama
# Modell wird beim ersten Start automatisch heruntergeladen (~4 GB)

Port 5743 nicht erreichbar

./manage.sh status
# Prüfen ob der Container läuft, dann:
docker compose ps

docker compose nicht gefunden

Prüfen ob Docker Compose als Plugin installiert ist:

docker compose version
# Falls nicht vorhanden, Docker aktualisieren oder Compose-Plugin installieren

UGREEN NAS: Permission denied bei manage.sh

chmod +x manage.sh
# Oder direkt ausführen:
sh manage.sh update

Windows: „manage.sh: command not found“ oder Syntax-Fehler

manage.sh ist ein Shell-Skript und läuft nicht direkt in PowerShell/cmd. Immer zuerst in WSL2 wechseln:

wsl
cd ~/infraquill
./manage.sh update

Docker Desktop → Einstellungen → Resources → WSL Integration: die genutzte Distribution muss aktiviert sein.

Unraid: Docker Compose nicht gefunden

Das Docker-Plugin von Unraid liefert docker compose i. d. R. mit. Falls nicht vorhanden, das „Compose Manager“-Plugin aus der Community Applications installieren.

---

Deinstallation

./manage.sh stop
docker compose down --volumes --rmi all

Achtung: --volumes löscht alle persistenten Daten inkl. der Ollama-Modelle. Ohne --volumes bleiben die Daten im data/-Ordner erhalten.