Kickstart Windows Setup

This document covers

• Setup kickstart develompent environment on Windows10

Setup Windows 11 workstation

This document assumes you have your project located in drive C:.

Update 2026/03/03: no .kickstartconfig is required anymore. Device Mapping and localhost Network schould work out of the box.

Requirements

• Installed Docker for Windows
• Activated Windows Subsystem 2 for Linux (WSL2)
  • Upgrade from WSL 1 to 2: wsl --set-version Ubuntu 2
• Installed Ubuntu for Windows

Additional

• Running Phpstorm “in” WSL2 and starting docker containers

Required Options in Docker for Windows

• Default Docker Desktop Settings should be sufficient
• Enable Windows WSL2 Mirrored Networking: (damit Zugriff auf localhost funktioniert)
  • wsl --update
  • wsl --shutdown

Configure the ubuntu shell

• Open the command line pompt and enter bash to enter the ubuntu shell

• If you see you are logged in as user root, you need to create a unprivileged user account inside the shell. Therefor execute:
  • Create a new user account inside the ubuntu shell and give it administrative privileges to run sudo:

    adduser <username>
    usermod -aG sudo <username>
    exit
    

  • Exit the ubuntu shell and set the default username by running:

    ubuntu config --default-user <username>
    

  • Run bash again: You should now be logged in as user
• You’re now in the ubuntu bash. Enter the following lines to configure kickstart for windows:

  sudo apt update && upgrade
  sudo apt install docker.io
  

  Warning: echo "export DOCKER_HOST=tcp://0.0.0.0:2375" >> ~/.kickstartconfig echo "export KICKSTART_WIN_PATH=C:/" >> ~/.kickstartconfig*is no more reliable for windows. WSL does path mapping itself! Do no more use KICKSTART_WIN_PATH and do not overwrite DOCKER_HOST!

Done

Go back to getting started guide and follow the instructions.

Checkout Project in WSL (Reload on FileChange)

To have vite / webpack recognize file changes (--watch - mode) it is mandatory to checkout projects directly in wsl (instead of Windows).

This is because Windows files are mounted into wsl without file update notifiers.

So clone projects directly inside the WSL: /home/user/xyz instead of /mnt/c/.... The IDE should recognize the path (tested with IntelliJ)

Frequent problems / solutions:

• Kickstart complains about /opt beeing empty

  This indicates, docker-daemon has no access to you local drive; Check if running docker run -it -v /mnt/C/path/toWorkdir:/opt ubuntu bash works and the current path is mounted in /opt.

  Solution: Open Docker for Windows. Go to Resources > File sharing. Remove all drives and add them again. You will be asked for your password. Access should be working right after.

• Kickstart complains about ports beeing already in use

  Kickstart normally requires ports 80,4000,4100,4200 not to be assigned already. Use netstat -ab on the windows shell to investigate the programs using these ports.