WSL-Integration (Windows-Subsystem für Linux).¶

Mit WSL können Sie eine vollständige Linux-Umgebung direkt unter Windows ausführen. Nach der Einrichtung funktioniert die STT-Shell-Integration identisch mit den Linux-Bash- oder Zsh-Anleitungen – für die Shell-Funktion selbst sind keine Windows-spezifischen Anpassungen erforderlich.

Empfohlen für: Windows-Benutzer, die mit einem Linux-Terminal vertraut sind oder WSL bereits für Entwicklungsarbeiten installiert haben. WSL bietet das zuverlässigste Erlebnis und die geringsten Kompatibilitätskompromisse.

Voraussetzungen¶

WSL installieren (einmalige Einrichtung)¶

Öffnen Sie PowerShell oder CMD als Administrator und führen Sie Folgendes aus:

wsl --install

Dadurch wird WSL2 standardmäßig mit Ubuntu installiert. Starten Sie Ihren Computer neu, wenn Sie dazu aufgefordert werden.

So installieren Sie eine bestimmte Distribution:

wsl --install -d Ubuntu-24.04
# or
wsl --install -d Debian

Alle verfügbaren Distributionen auflisten:

wsl --list --online

Überprüfen Sie Ihre WSL-Version¶

wsl --list --verbose

Stellen Sie sicher, dass in der Spalte „VERSION“ „2“ angezeigt wird. Wenn „1“ angezeigt wird, aktualisieren Sie mit:

wsl --set-version <DistroName> 2

Shell-Integration innerhalb der WSL¶

Sobald WSL ausgeführt wird, öffnen Sie Ihr Linux-Terminal und folgen Sie der Linux-Shell-Anleitung für Ihre bevorzugte Shell:

Schale	Leitfaden
Bash (WSL-Standard)	bash-integration.md
Zsh	zsh-integration.md
Fisch	fish-integration.md
Ksh	ksh-integration.md
POSIX sh / Dash	posix-sh-integration.md

Für das standardmäßige Ubuntu/Debian-WSL-Setup mit Bash lautet der Schnellpfad:

nano ~/.bashrc
# Paste the function block from bash-integration.md
source ~/.bashrc

WSL-spezifische Überlegungen¶

Zugriff auf Windows-Dateien über die WSL¶

Ihre Windows-Laufwerke werden unter „/mnt/“ gemountet:

/mnt/c/   # → C:\
/mnt/d/   # → D:\

Wenn sich Ihr Projekt im Windows-Dateisystem befindet (z. B. „C:\Projects\stt“), setzen Sie „SL5NET_AURA_PROJECT_ROOT“ auf:

export SL5NET_AURA_PROJECT_ROOT="/mnt/c/Projects/stt"

Fügen Sie diese Zeile zu Ihrem „~/.bashrc“ (oder dem Äquivalent für Ihre Shell) über der Funktion „s()“ hinzu.

Leistungstipp: Für eine optimale E/A-Leistung sollten Sie die Projektdateien im WSL-Dateisystem (z. B. „~/projects/stt“) und nicht in „/mnt/c/…“ aufbewahren. Der dateisystemübergreifende Zugriff zwischen WSL und Windows ist deutlich langsamer.

Virtuelle Python-Umgebung innerhalb der WSL¶

Erstellen und verwenden Sie eine standardmäßige virtuelle Linux-Umgebung innerhalb der WSL:

cd "$SL5NET_AURA_PROJECT_ROOT"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Der „PY_EXEC“-Pfad in der Funktion („$SL5NET_AURA_PROJECT_ROOT/.venv/bin/python3“) funktioniert unverändert korrekt.

Ausführen von „s“ über das Windows-Terminal¶

Windows Terminal ist die empfohlene Methode zur Verwendung von WSL unter Windows. Es unterstützt mehrere Registerkarten, Bereiche und Profile für jede WSL-Verteilung. Installieren Sie es aus dem Microsoft Store oder über:

winget install Microsoft.WindowsTerminal

Legen Sie Ihre WSL-Distribution als Standardprofil in den Windows-Terminal-Einstellungen fest, um ein möglichst nahtloses Erlebnis zu gewährleisten.

Docker On-Demand (Linux)¶

Um Systemressourcen zu sparen, können Sie Docker so konfigurieren, dass es nur bei Bedarf startet (z. B. wenn Aura die Trino-Datenbank anfordert) und nicht ständig im Hintergrund läuft.

Führen Sie die folgenden Befehle aus, um den kontinuierlichen Hintergrunddienst zu deaktivieren und stattdessen die „Socket-Aktivierung“ zu aktivieren:

sudo systemctl disable docker.service
sudo systemctl enable docker.socket
sudo systemctl start docker.socket

Aktualisierungssicher machen (Linux Arch/Manjaro-Benutzer): Paketaktualisierungen können manchmal die Socket-Konfiguration zurücksetzen. Um dies zu verhindern, erstellen Sie eine dauerhafte lokale Überschreibung:

sudo systemctl edit docker.socket

Stellen Sie sicher, dass die folgenden Zeilen vorhanden und unkommentiert sind (entfernen Sie das „#“), speichern Sie dann und beenden Sie den Vorgang:

[Install]
WantedBy=sockets.target

Docker und Kiwix innerhalb der WSL¶

Das Kiwix-Hilfsskript („kiwix-docker-start-if-not-running.sh“) erfordert Docker. Installieren Sie Docker Desktop für Windows und aktivieren Sie die WSL 2-Integration:

Laden Sie Docker Desktop herunter und installieren Sie es.
Aktivieren Sie in Docker Desktop → Einstellungen → Ressourcen → WSL-Integration Ihre WSL-Verteilung.
Überprüfen Sie innerhalb der WSL:
```
docker --version
```

Aufrufen der WSL-Funktion „s“ unter Windows (optional)¶

Wenn Sie die Verknüpfung „s“ von einem Windows CMD- oder PowerShell-Fenster aus aufrufen möchten, ohne ein WSL-Terminal zu öffnen, können Sie sie wie folgt umschließen:

# PowerShell wrapper
function s { wsl bash -i -c "s $args" }

:: CMD wrapper — save as s.bat on your PATH
@echo off
wsl bash -i -c "s %*"

Das Flag „-i“ lädt eine interaktive Shell, sodass Ihr „~/.bashrc“ (und die Funktion „s“) automatisch als Quelle verwendet werden.

Merkmale¶

Volle Linux-Kompatibilität: Alle Unix-Tools („timeout“, „pgrep“, „mktemp“, „grep“) funktionieren nativ – keine Problemumgehungen erforderlich.
Dynamische Pfade: Findet automatisch das Projektstammverzeichnis über die Variable „SL5NET_AURA_PROJECT_ROOT“, die in Ihrer Shell-Konfiguration festgelegt ist.
Automatischer Neustart: Wenn das Backend ausgefallen ist, versucht es, „start_service“ und lokale Wikipedia-Dienste auszuführen (Docker muss ausgeführt werden).
Intelligente Zeitüberschreitungen: Versucht zunächst eine schnelle 2-Sekunden-Reaktion und fällt dann auf einen 70-Sekunden-Tiefverarbeitungsmodus zurück.