Ga naar hoofdinhoud
AcademytutorialWorkstation Setup leerlijn — Deel 2: De basis inrichten

Workstation Setup leerlijn — Deel 2: De basis inrichten

WSL2, Docker Desktop, VS Code met de juiste extensies, Node, PHP, Codeberg-auth (SSH-sleutel + tea CLI) plus de GitHub CLI, de OpenSpec CLI en de Playwright-browser. Het langste deel van de leerlijn — de meeste tijd gaat in downloads waar je naast iets anders kunt doen. Na dit deel heb je een werkend dev-workstation, alleen Claude Code is nog niet aangesloten.

TutorialWorkstationSetupWSL2DockerVS CodeNodePHPCodebergTutorial series
Conduction·29 mei 202616 min read

Dit is het deel met de meeste installatie-commando's. WSL2, Docker Desktop, VS Code met de juiste extensies, de language-runtimes (Node, PHP, Composer), de CLI's (gh, OpenSpec) en de Playwright Chromium-binary. Aan het einde van Deel 2 heb je een werkend dev-workstation — alleen Claude Code is nog niet aangesloten. Dat is Deel 3.

Een opmerking over macOS en Linux

Dit deel gaat uit van Windows 11. Werk je op macOS of Linux:

  • macOS — sla stap 1 (WSL2) volledig over. Vervang apt install door brew install in de rest. Installeer Docker Desktop native. De volgorde en de verificatie-commando's blijven hetzelfde.
  • Linux native — sla stap 1 (WSL2) over. Installeer Docker Engine native (geen Docker Desktop). De volgorde blijft hetzelfde.

Onze canonical workstation-setup.md beschrijft het Windows + WSL2-pad; de macOS- en Linux-varianten hierboven zijn de vertaling die de meeste teams gebruiken. Loop je tegen iets aan dat niet één-op-één vertaalt, stuur dan onderaan even een berichtje via Mail ons.

Stap 1: installeer WSL2 (alleen Windows)

Open PowerShell als Administrator — rechtsklik op de Start-knop, kies "Terminal (Admin)" of "PowerShell (Admin)" — en draai dan:

wsl --install -d Ubuntu-24.04

Herstart je machine als daarom wordt gevraagd. Na de reboot rondt Ubuntu zijn eerste setup af en vraagt om een Linux-username en -wachtwoord. Kies een username die je onthoudt; het wachtwoord is het sudo-wachtwoord voor je Ubuntu-installatie.

Verifieer in PowerShell:

wsl --version
wsl -l -v

Je hoort Ubuntu-24.04 draaiend op WSL versie 2 te zien.

Geen reboot? Herstart Ubuntu via wsl --shutdown in PowerShell en open de Ubuntu-app opnieuw. Dat lost negen van de tien "hij wil gewoon niet starten"-problemen op.

Stap 2: installeer Docker Desktop

Download Docker Desktop voor Windows van docker.com/products/docker-desktop en installeer het. Na de installatie:

  1. Open Docker Desktop > Settings > Resources > WSL Integration.
  2. Schakel de integratie met je Ubuntu-24.04-distro in.
  3. Klik op Apply & Restart.

Open je Ubuntu-terminal (Start-menu → Ubuntu) en verifieer:

docker --version
docker compose version

Beide moeten een versie-string teruggeven. Meldt docker --version "command not found" binnen WSL, dan is de WSL-integratie niet toegepast — sluit Docker Desktop volledig af (rechtsklik op het tray-icoon → Quit) en start het opnieuw.

Stap 3: installeer VS Code

Download Visual Studio Code van code.visualstudio.com en installeer het op Windows (niet binnen WSL).

Verbind het daarna met WSL:

  1. Open VS Code.
  2. Ctrl+Shift+X om Extensions te openen, installeer WSL (ms-vscode-remote.remote-wsl) aan de Windows-kant. Deze moet echt op Windows staan, niet in WSL.
  3. Ctrl+Shift+P > "WSL: Connect to WSL".
  4. Kies Ubuntu-24.04.

VS Code installeert zijn server-component automatisch binnen WSL. Vanaf nu draait elke VS Code-terminal binnen WSL.

Stap 4: installeer VS Code-extensies

Installeer in het WSL-gekoppelde VS Code-venster deze extensies. Het makkelijkst gaat dat vanaf de WSL-terminal:

code --install-extension anthropic.claude-code
code --install-extension ms-azuretools.vscode-docker
code --install-extension bmewburn.vscode-intelephense
code --install-extension vue.volar
code --install-extension dbaeumer.vscode-eslint
code --install-extension ms-python.python
code --install-extension eamodio.gitlens
code --install-extension redhat.vscode-yaml
code --install-extension github.vscode-github-actions

Daarmee dek je de verplichte + aanbevolen set voor een Conduction-project. Zie workstation-setup.md voor de optionele.

Stap 5: installeer Node (via nvm)

Al het Node-werk gebeurt binnen WSL, nooit aan de Windows-kant. Gebruik nvm zodat je per project van versie kunt wisselen zonder sudo:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm alias default 20

Verifieer:

node --version    # v20.x
npm --version     # 10.x

Waarom Node 20, niet de nieuwste? Docusaurus 3.x en de OpenSpec-CLI willen allebei Node 20+, en onze canonical workstation-setup.md installeert specifiek Node 20. Blijf bij 20 LTS tot je een reden hebt om dat niet te doen.

Stap 6: installeer PHP 8.1+ en Composer

sudo apt update
sudo apt install -y php8.1-cli php8.1-xml php8.1-mbstring php8.1-curl php8.1-zip unzip
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Verifieer:

php --version       # 8.1+
composer --version  # 2.x

Gebruik phpcs v3, niet v4, als een project erom vraagt. De CI is op v3 gepind en v4 breekt de gedeelde phpcs.xml-config. Probeert een latere composer install te upgraden, override dan met composer require --dev "squizlabs/php_codesniffer:^3.9".

Stap 7: Codeberg-auth (SSH + tea)

Conduction is in mei 2026 verhuisd van github.com/ConductionNL naar codeberg.org/Conduction — Codeberg is nu de primaire git-host, GitHub blijft als secundaire mirror staan. In deze stap zet je twee dingen op: SSH (voor git clone/push/pull) en de tea CLI (voor PR's, issues, labels via de Codeberg REST-API). Beide blijven over reboots heen werken zodra ze geconfigureerd zijn.

Dit is de condensed walkthrough. De volledige versie, met elke troubleshooting-case en diepere achtergrond, staat in Codeberg Authentication Setup in de .github repo. Lees die als hieronder iets niet werkt.

7a. Genereer een SSH-sleutel en voeg hem toe aan Codeberg

ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519_codeberg

Geef een passphrase op als hij erom vraagt — keychain (volgende stap) zorgt dat je hem in de praktijk nauwelijks intikt, en een passphrase-loze sleutel op schijf is voor iedereen die het bestand kan lezen een complete credential.

Kopieer de publieke sleutel (het .pub-bestand) naar Codeberg:

cat ~/.ssh/id_ed25519_codeberg.pub
# of pijp direct naar het Windows-klembord vanuit WSL:
cat ~/.ssh/id_ed25519_codeberg.pub | clip.exe

Ga naar codeberg.org/user/settings/keys → Add Key, plak de hele regel, geef hem een herkenbare naam (bijv. WSL Ubuntu — <laptop>), klik Add Key.

7b. Laat SSH de juiste sleutel kiezen voor Codeberg

cat >> ~/.ssh/config <<'EOF'

Host codeberg.org
  HostName codeberg.org
  User git
  IdentityFile ~/.ssh/id_ed25519_codeberg
  IdentitiesOnly yes
EOF
chmod 600 ~/.ssh/config

chmod 600 is verplicht — SSH negeert een config-bestand met ruimere rechten stilzwijgend.

Verifieer:

ssh -T [email protected]
# Hi there, <JouwCodebergUsername>! You've successfully authenticated...

7c. Houd de sleutel geladen over shells heen met keychain

Zonder keychain vraagt elke git push opnieuw om de passphrase. Met keychain geef je de passphrase één keer per WSL-boot op en elke volgende shell (inclusief Claude Code's Bash-tool) erft de ontgrendelde agent.

sudo apt install -y keychain
cat >> ~/.bashrc <<'EOF'

# Houd een ssh-agent in leven over shells heen, met de Codeberg-sleutel geladen
eval $(keychain --eval --quiet --agents ssh ~/.ssh/id_ed25519_codeberg)
EOF

Open een nieuwe terminal — keychain vraagt nu eenmalig om de passphrase. Daarna:

ssh-add -l
# 256 SHA256:... [email protected] (ED25519)

7d. Installeer de tea CLI voor PR's, issues en labels

SSH dekt het git-protocol. Alles wat daarbuiten valt (een PR aanmaken, issues lijsten, labels zetten) loopt via de Codeberg REST-API. tea is Gitea's officiële CLI — beschouw het als gh voor Codeberg.

sudo wget -O /usr/local/bin/tea https://dl.gitea.com/tea/0.11.0/tea-0.11.0-linux-amd64
sudo chmod +x /usr/local/bin/tea
tea --version

7e. Maak een Codeberg API-token en vertel tea ervan

Ga naar codeberg.org/user/settings/applications → Generate New Token met deze scopes (vink write waar van toepassing): repository, issue, user, organization. Zet de geldigheid op 90 dagen; roteer per kwartaal. Kopieer de token meteen — Codeberg toont hem maar één keer.

tea login add --name codeberg --url https://codeberg.org --token <plak-token-hier>
tea login list
# NAME=codeberg  URL=https://codeberg.org  USER=<JouwCodebergUsername>

De token zit vanaf nu in ~/.config/tea/config.yml; elke tea-aanroep hergebruikt hem.

7f. Installeer de GitHub CLI (secundair, nog steeds nuttig)

Een handvol repo's leeft nog op GitHub en Hydra's cron-scripts zijn nog niet gemigreerd, dus gh blijft in de toolbox:

sudo apt install -y gh
gh auth login   # GitHub.com → HTTPS → Login with a web browser

Gebruikt je werk-GitHub SSO, zorg er dan voor dat je standaardbrowser Edge of Chrome is — Firefox-SSO-callbacks komen soms niet schoon terug.

Verifieer alledrie:

ssh -T [email protected]   # → "Hi there, <JouwCodebergUsername>!"
tea login list            # → rij met NAME=codeberg
gh auth status            # → groen vinkje + je GitHub-username

Stap 8: installeer de OpenSpec CLI

Gebruikt door alle /opsx-*-skills voor spec-driven development:

npm install -g @fission-ai/openspec
openspec --version

Draai GEEN openspec init binnen een Conduction-project — die projecten hebben al een aangepaste openspec/-map. init draaien overschrijft die.

Stap 9: installeer de Playwright Chromium-binary

De Playwright MCP-browsers (gebruikt door onze testing-skills) hebben Chromium nodig, eenmalig op deze machine te installeren:

npx playwright install chromium

De download is ~300 MB. Draai hem op een stabiele verbinding — niet in de trein.

Stap 10: alles verifiëren

Een schoon dev-workstation komt zonder fouten door deze checklist heen:

node --version            # v20.x
npm --version             # 10.x
php --version             # 8.1+
composer --version        # 2.x
docker --version          # 24+
docker compose version    # 2.x
ssh -T [email protected]   # "Hi there, <JouwCodebergUsername>!"
tea --version             # 0.11+
tea login list            # rij met NAME=codeberg
gh --version              # 2.x
gh auth status            # groen vinkje + je GitHub-username
openspec --version        # 1.x
npx playwright --version  # 1.x

Geeft elk commando een echte versie terug en is gh auth status groen, dan ben je klaar met Deel 2. Zo niet, spring dan naar Troubleshooting hieronder.

Troubleshooting

WSL2 wil niet installeren: 'WSL is not supported on this version of Windows'

Je zit waarschijnlijk op Windows 10 zonder de laatste cumulatieve update, of op Home-editie zonder virtualisatie aan. Werk Windows bij, zet daarna Virtual Machine Platform en Windows Subsystem for Linux aan via Windows-onderdelen in- of uitschakelen. Reboot en probeer opnieuw.

docker-commando niet gevonden binnen WSL na het installeren van Docker Desktop

De WSL-integratie is niet toegepast. Open Docker Desktop > Settings > Resources > WSL Integration, schakel Ubuntu-24.04 uit en weer aan, klik op Apply & Restart. Open daarna de Ubuntu-terminal opnieuw.

composer install faalt met 'vendor/ is owned by root'

Gebeurt na de eerste Docker-run in een project — Docker heeft vendor/ als root aangemaakt. Twee fixes: (1) sudo chown -R $USER:$USER vendor/ en opnieuw draaien, of (2) installeer phpcs globaal met composer global require "squizlabs/php_codesniffer:^3.9" en sla composer install voor nu over.

gh auth login opent de verkeerde browser en SSO komt niet rond

Gebruikt je werk-GitHub SSO en is Firefox de standaardbrowser, dan komt de callback soms niet schoon terug. Zet Edge of Chrome als standaardbrowser en draai gh auth login --web opnieuw.

ssh -T [email protected] geeft 'Permission denied (publickey)'

Of je publieke sleutel staat niet op Codeberg, of ~/.ssh/config heeft niet chmod 600. Plak ~/.ssh/id_ed25519_codeberg.pub opnieuw op codeberg.org/user/settings/keys en draai chmod 600 ~/.ssh/config. Probeer dan opnieuw.

Elke git push vraagt opnieuw om de SSH-passphrase

keychain is niet geïnstalleerd, of de eval $(keychain ...)-regel staat niet in ~/.bashrc. Open een verse terminal na het editen van ~/.bashrc — keychain draait alleen bij shell-start. Verifieer met ssh-add -l; je hoort de Codeberg-sleutel in de lijst te zien.

tea pulls create geeft 401 Unauthorized

De token in ~/.config/tea/config.yml mist write:repository of write:issue. Genereer de token opnieuw op codeberg.org/user/settings/applications met de juiste scopes (zie Stap 7e) en draai tea login add opnieuw.

npx playwright install chromium hangt of geeft een timeout

De download is ~300 MB. Op een trage verbinding lijkt het soms vast te zitten. Wacht hem uit, of draai hem op een snellere verbinding. Wil hij écht niet, zet dan HTTPS_PROXY en probeer opnieuw vanaf een netwerk waar de proxy resolvet.

Test jezelf

Vijf korte vragen om te checken of je dit deel begrepen hebt. Vastgelopen? Klik Hint. Curieus naar het antwoord? Klik Antwoord.

1. Waarom installeren we Node, PHP en de rest binnen WSL in plaats van aan de Windows-kant?

Hint

Denk na over welk filesystem de tooling leest en schrijft, en welke shell-scripts de latere stappen draaien.

Antwoord

Omdat elke latere stap — Composer, de OpenSpec-CLI, de gh-CLI, de globale Claude safety hooks (Deel 3) — uitgaat van een POSIX-shell en Linux-bestandspaden.

Node of PHP op Windows installeren leidt tot dubbele path-translaties (\\wsl$\... ↔ C:\Users\...), inconsistente line endings en bash hooks die simpelweg niet draaien. De vuistregel: alles wat je vanuit een shell draait gaat binnen WSL; editor en Docker Desktop draaien op Windows.

2. Het Docker-commando werkt in Windows PowerShell maar niet binnen WSL. Wat is de meest waarschijnlijke oorzaak?

Hint

Docker Desktop draait op Windows. Er is een expliciete stap nodig om hem vanuit WSL bereikbaar te maken.

Antwoord

De WSL Integration stond niet aan (of is niet toegepast) voor je Ubuntu-distro. Open Docker Desktop > Settings > Resources > WSL Integration, schakel je Ubuntu-distro uit en weer aan, klik op Apply & Restart. Open daarna de Ubuntu-terminal opnieuw.

Helpt dat nog niet, sluit Docker Desktop dan volledig af (rechtsklik op het tray-icoon → Quit) en start het opnieuw. Dat dekt de laatste 10% van de gevallen.

3. Waarom installeren we de WSL-extensie voor VS Code aan de Windows-kant, en de rest aan de WSL-kant?

Hint

De WSL-extensie doet één specifiek ding dat de andere extensies niet doen.

Antwoord

De WSL-extensie is wat VS Code op Windows koppelt aan een remote VS Code Server binnen WSL — die stap moet aan de Windows-kant gebeuren. Zodra die verbinding staat, hebben de andere extensies (Claude Code, Volar, ESLint, Intelephense, Docker) toegang nodig tot je code, je node_modules en je shell — dus installeer je ze aan de WSL-kant, tegen hetzelfde filesystem als je project.

Taal-extensies op Windows installeren terwijl de code in WSL staat geeft je kapotte IntelliSense, trage file watchers en verwarrende path-fouten. Houd de regel simpel: WSL-extensie op Windows, al het andere binnen WSL.

4. Je git push naar een Codeberg-repo hangt twee minuten stil en faalt dan met "Permission denied (publickey)". Wat zijn de twee meest waarschijnlijke oorzaken, en hoe onderscheid je ze?

Hint

De één gaat erover of de sleutel bekend is bij Codeberg. De ander gaat erover of de sleutel ontgrendeld is op je machine. Twee aparte failure modes; twee aparte checks.

Antwoord

De twee failure modes zijn:

  1. De publieke sleutel is niet gekoppeld aan je Codeberg-account. Diagnose: cat ~/.ssh/id_ed25519_codeberg.pub en vergelijk met de sleutels op codeberg.org/user/settings/keys. Staat hij er niet tussen, plak hem erin.
  2. De sleutel staat op Codeberg, maar geen enkele ssh-agent heeft hem geladen op deze machine. Diagnose: ssh-add -l. Als de output "The agent has no identities" is, is keychain of niet geïnstalleerd, of draait hij niet in deze shell. Draai eenmalig keychain ~/.ssh/id_ed25519_codeberg en open een verse terminal.

In beide gevallen hoort ssh -T [email protected] na de fix te antwoorden met "Hi there, <jouw username>!" — de meest waterdichte enkele bevestiging dat auth werkt.

5. Na de eerste docker compose up -d van een Conduction-project faalt composer install op de host opeens met Permission denied op vendor/. Wat is er gebeurd, waarom juist bij de eerste Docker-run, en wat is de snelste fix?

Hint

Docker-containers draaien standaard als root. Wanneer een container in een bind-mounted directory schrijft, erven de bestanden die ownership op de host.

Antwoord

Wanneer Docker een Conduction-project voor het eerst opstart, schrijft de PHP-container in de bind-mounted vendor/-directory — maar de container draait als root, dus de resulterende bestanden zijn op het host file system eigendom van root:root. Je host-user ($USER) kan er niet in schrijven, en composer install vanaf de host faalt.

Waarom juist bij de eerste run: daarvóór bestond vendor/ nog niet of was hij schoon. Volgende runs hergebruiken de al-root-owned bestanden, dus de fout blijft staan tot je de ownership fixt.

Snelste fix:

sudo chown -R $USER:$USER vendor/
composer install

Alternatief als je geen sudo wilt gebruiken: installeer phpcs globaal (composer global require "squizlabs/php_codesniffer:^3.9") en sla de lokale composer install voorlopig over. CI gebruikt nog steeds de composer.json van het project, dus dit raakt alleen je lokale tooling.

Volgende stap

Met de runtimes geïnstalleerd is het tijd om Claude Code zelf op te zetten — en, minstens zo belangrijk, de globale safety hooks.

Deel 3 — Claude Code installeren en configureren
Lees meer
De canonical workstation-setup.md
Lees meer