#Lokale Entwicklungsumgebung unter Windows mit WSL einrichten

Für lokale NocoBase-Entwicklung unter Windows empfehlen wir zuerst WSL 2. So laufen Node.js, Yarn, NocoBase CLI, Docker-Befehle und AI Agents in derselben Linux-Shell, mit Pfaden, Berechtigungen und nativen Builds näher an typischen Linux-Deployments.

Wenn du noch nicht sicher bist, ob du WSL brauchst, lies zuerst Lokale Entwicklungsumgebung einrichten.

#Vorbereitung

Prüfe vor der Installation von WSL die Windows-Version und den Virtualisierungsstatus.

#Windows-Version prüfen

Drücke Win + R, gib winver ein und bestätige, dass dein System eine der folgenden Anforderungen erfüllt:

• Windows 11
• Windows 10 version 2004 or later, Build 19041 or later

Wenn die Version älter ist, aktualisiere Windows, bevor du fortfährst.

#Virtualisierung prüfen

Öffne den Task-Manager, gehe zu Leistung / CPU und bestätige, dass Virtualisierung als Aktiviert angezeigt wird.

Wenn Virtualisierung nicht aktiviert ist, aktiviere sie im BIOS / UEFI. Die Option heißt je nach Hersteller Intel VT-x, Intel Virtualization Technology, AMD-V oder SVM Mode.

#Schritt 1: WSL 2 installieren

Öffne PowerShell als Administrator:

1. Windows-Startmenü öffnen
2. PowerShell
3. Mit der rechten Maustaste Als Administrator ausführen wählen

Ausführen:

wsl --install

Starte den Computer nach der Installation neu.

Standardmäßig installiert dieser Befehl Ubuntu. Beim ersten Start fordert Ubuntu dich auf, einen Linux-Benutzernamen und ein Passwort zu erstellen. Diese gelten nur innerhalb von WSL.

Wenn du eine bestimmte Distribution installieren möchtest, liste zuerst die verfügbaren Distributionen auf:

wsl --list --online

Installiere dann eine Distribution, zum Beispiel Ubuntu:

wsl --install -d Ubuntu

#Schritt 2: WSL-Version bestätigen

Führe in PowerShell aus:

wsl --list --verbose

Die Ausgabe sollte ungefähr so aussehen:

  NAME      STATE           VERSION
* Ubuntu    Running         2

Bestätige, dass VERSION den Wert 2 hat. Wenn eine Distribution noch WSL 1 verwendet, konvertiere sie zu WSL 2:

wsl --set-version Ubuntu 2

Setze WSL 2 außerdem als Standard für neu installierte Distributionen:

wsl --set-default-version 2

Du kannst WSL auch einmal aktualisieren:

wsl --update

#Schritt 3: Docker Desktop installieren

Wenn du NocoBase mit Docker installieren oder ausführen möchtest, installiere Docker Desktop for Windows.

• Install Docker Desktop on Windows

Achte bei der Installation auf diese Optionen:

1. Für persönliche lokale Entwicklung reicht normalerweise Per-user
2. Use WSL 2 instead of Hyper-V
3. Starte Docker Desktop nach der Installation über das Windows-Startmenü
4. Lies und akzeptiere beim ersten Start das Docker Desktop Subscription Service Agreement

#Schritt 4: Docker WSL Integration aktivieren

Nachdem Docker Desktop gestartet ist, prüfe zuerst, dass das WSL-2-Backend aktiviert ist:

1. Docker Desktop / Settings / General
2. Use the WSL 2 based engine
3. Apply

Aktiviere danach die Integration für die Distribution:

1. Docker Desktop / Settings / Resources / WSL Integration
2. Enable integration with my default WSL distro
3. Ubuntu
4. Apply & restart / Apply

Wenn WSL Integration unter Resources nicht erscheint, läuft Docker Desktop meist im Windows-containers-Modus. Wechsle über das Docker-Symbol im Windows-Infobereich zu Linux containers und prüfe erneut.

#Schritt 5: Docker prüfen

Prüfe zuerst in PowerShell:

wsl --list --verbose
docker version
docker compose version
docker run hello-world

Wechsle dann in WSL:

wsl

Führe in WSL aus:

docker version
docker compose version
docker run hello-world

Wenn der hello-world-Container erfolgreich geladen und ausgeführt wird, funktioniert die Integration von Docker Desktop und WSL 2.

#Schritt 6: Node.js und Yarn in WSL installieren

WSL selbst ist keine Node.js-Laufzeitumgebung. Das mit wsl --install installierte Ubuntu enthält normalerweise kein Node.js und npm, daher installierst du sie innerhalb der WSL-Distribution.

wsl

Alle folgenden Befehle werden im WSL-Terminal ausgeführt. Prüfe zuerst, ob Node.js bereits installiert ist:

node -v
npm -v

Wenn command not found erscheint, installiere Node.js mit einer der folgenden Methoden.

#Variante A: Node.js 22 mit NodeSource installieren

Wenn diese WSL-Umgebung nur eine gemeinsame Node.js-Version braucht, ist NodeSource empfehlenswert.

sudo apt update
sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs

Installation prüfen:

node -v
npm -v
npx -v

#Variante B: Node.js 22 mit nvm installieren

Wenn du zwischen Projekten Node.js-Versionen wechseln musst oder ein Projekt .nvmrc nutzt, verwende nvm.

sudo apt update
sudo apt install -y curl ca-certificates
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

Wenn das Projekt Node.js 22 festlegen soll, erstelle .nvmrc:

echo "22" > .nvmrc
nvm install
nvm use

#Yarn 1.x installieren

Für lokale NocoBase-Entwicklung wird Yarn 1.x benötigt. Nach der Node.js-Installation kannst du Yarn über Corepack aktivieren:

corepack enable
corepack prepare yarn@1.22.22 --activate
yarn -v

Wenn Corepack in deiner Umgebung nicht verfügbar ist, installiere Yarn mit npm:

npm install -g yarn@1.22.22
yarn -v

#Schritt 7: Codex CLI installieren

Codex CLI kann auch in der nativen Windows-Befehlszeile verwendet werden. In dieser Anleitung wird es in WSL installiert, damit Codex und die NocoBase-Toolchain in derselben Linux-Umgebung bleiben.

echo $WSL_DISTRO_NAME

Führe den Codex-CLI-Installer in WSL aus:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Für eine nicht-interaktive Installation:

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

Nach der Installation ausführen und Version prüfen:

codex
codex --version

Starte Codex am besten aus einem Projektverzeichnis innerhalb von WSL:

mkdir -p ~/projects
cd ~/projects/my-app
codex

#Wo Projektdateien liegen sollten

Lege Projektdateien am besten im WSL-Dateisystem ab, zum Beispiel:

~/projects/my-app

Vermeide Windows-Mount-Pfade als Standard-Projektort, zum Beispiel:

/mnt/c/Users/<your-name>/projects/my-app

Das bringt meist bessere Dateisystemleistung und reduziert Probleme mit Symlinks und Berechtigungen.

Um WSL-Dateien im Windows Explorer zu öffnen, verwende:

\\wsl$\Ubuntu\home\<your-name>

#FAQ

#WSL meldet, dass der docker-Befehl nicht gefunden wurde

Prüfe zuerst, ob die Distribution WSL 2 verwendet:

wsl --list --verbose
wsl --set-version Ubuntu 2

Aktiviere danach in Docker Desktop unter Settings / Resources / WSL Integration die Integration für die entsprechende Distribution.

#WSL Integration fehlt

Meist befindet sich Docker Desktop im Windows-containers-Modus. Wechsle über das Docker-Symbol im Infobereich zu Linux containers und öffne die WSL-Integration erneut.

#Docker Desktop startet nicht oder WSL wirkt fehlerhaft

Versuche zuerst, WSL herunterzufahren und zu aktualisieren, und starte danach Docker Desktop neu:

wsl --shutdown
wsl --update

#Docker Engine wurde manuell in WSL installiert

Docker empfiehlt, vor der Installation von Docker Desktop direkt in WSL installierte Docker Engine- oder Docker CLI-Pakete zu entfernen, um Konflikte mit der WSL-Integration zu vermeiden.

#WSL meldet, dass der codex-Befehl nicht gefunden wurde

Prüfe zuerst, ob du wirklich in WSL bist, prüfe danach PATH und führe den Installer bei Bedarf erneut aus:

echo $WSL_DISTRO_NAME
which codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

#Offizielle Referenzen

• Microsoft Learn: How to install Linux on Windows with WSL
• Microsoft Learn: Install Node.js on Windows Subsystem for Linux
• Docker Docs: Install Docker Desktop on Windows
• Docker Docs: Docker Desktop WSL 2 backend on Windows
• Docker Docs: Change your Docker Desktop settings
• OpenAI Developers: Codex CLI
• OpenAI Developers: Codex on Windows
• nvm: Node Version Manager
• npm Docs: Downloading and installing Node.js and npm