Getting started with Windows
There are special considerations involved with getting an environment set up in Windows, notably with:
- 1.Setting up Docker with a Windows Subsystem for Linux (WSL 2) backend
- 2.Setting up an IDE
We recommend running Docker in Windows with WSL 2.
- 1.Join the Windows Insider Program (not recommended)
- 2.Manually install WSL 2
Windows Insider Program may not be available on corporate devices.
You’ll need to have virtualization enabled on your machine. To check if you have virtualization enabled: open the Task Manager, go to the Performance tab, and under CPU verify
Windows task manager virtualization check
PowerShell does not recognize
Solution: Reinstall WSL, making sure you run everything with administrator privileges.
wslcommands with PowerShell generates the following error:
WSL error: service cannot be started
You won't be able to install a Linux distribution from the Microsoft Store if you don't have privileges to access the store.
In your WSL distribution, you can
pingyour favorite website to check for internet connectivity.
Multi-part solution: First, make sure your Linux distribution is connected to the right DNS server. The DNS server used by Windows can be identified with
IPCONFIG /ALL | FIND /I "DNS Server"in the command prompt. The DNS server used by Linux is found in the
/etc/resolv.conffile. They should be the same.
As you install Docker, make sure you install the required Windows components for WSL 2.
Docker install with WSL components
Once installed, check
Settings > Generalto make sure WSL is used.
Docker is using WSL
Settings > Resources > WSL Integrationto select your Linux distribution.
Docker is using specified Linux distribution
No WSL 2 distribution found
Docker may not be able to find any WSL 2 distributions. This means your distributions are configured with WSL 1.
Docker error: no WSL 2 distributions found
Solution: You can try to upgrade the distribution with
wsl --set-version <distro-name> 2(e.g.
wsl --set-version Ubuntu-20.04 2). If this doesn't work, you can uninstall and reinstall it.
Linux distribution is not running
For some reason, the distribution may not be running. You can check by running
wsl -l -v. You'll want everything to be running with version 2:
WSL all instances running with version 2
Docker fails to start
Solution: In Docker Desktop, click the bug icon in the top right corner. Try
Restart Docker Desktopand restart your computer. If that isn't strong enough, try
Reset to factory defaultsand restart your computer. If that still doesn't work, uninstall Docker and reinstall it.
If things are working, you'll be able to run CiviForm in WSL with Docker using the following steps:
There are two options for configuring an IDE:
- 1.(faster to set up, slower development time): store and edit files directly in Windows (e.g. C:) and use WSL to run the
- 2.(more setup, faster development time): Store, edit, and run everything from within WSL 2.
- 1.From WSL,
git clonethe CiviForm repository somewhere in your Windows file system (
- 5.Open IntelliJ, download the Scala plugin, and restart IntelliJ.
- 7.Wait for a while for IntelliJ to index the project.
The files are stored in Windows, and WSL is used to run
You'll need a UI to access an IDE in WSL. A couple options:
From within WSL:
git clonethe CiviForm repository in WSL
- 1.Install zip using
sudo apt install zip unzip
- 3.Install IntelliJ.
- 4.Open IntelliJ, download the Scala plugin, and restart IntelliJ.
- 6.Wait for a while for IntelliJ to index the project.