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
Note: If virtualization is disabled, you’ll need to boot up into the BIOS and enable virtualization. If your machine does not support virtualization you won't be able to proceed.
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
Solution: From WSL GitHub issue 3386: in the command prompt (not PowerShell) with administrator privileges, execute
sc config LxssManager start=auto
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.
Note: If you already had Docker installed before setting up WSL 2, you may want to uninstall and reinstall Docker so it installs with the required components for WSL 2.
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:
- 3.In a browser, go to
localhost:9000, and then wait for the application to load.
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.
Note: It's slow to run start and test the application when the files are stored in Windows because Docker runs in WSL, and will be accessing files through the
- 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.
Note: While waiting for step 6, you may need to restart IntelliJ. This step takes a long time, but it takes a long time the first time.**
The files are stored in Windows, and WSL is used to run
Note: You may need to configure the IDE to use Linux line endings.
You'll need a UI to access an IDE in WSL. A couple options:
From within WSL:
git clonethe CiviForm repository in WSL
Note: Do not clone into
- 1.Install zip using
sudo apt install zip unzip
- 2.Install sdkman, and use it to install
sdk install java 11.0.10-open,
sdk install sbt 1.3.13, and
sdk install scala 2.13.1.
- 3.Install IntelliJ.
- 4.Open IntelliJ, download the Scala plugin, and restart IntelliJ.
- 6.Wait for a while for IntelliJ to index the project.
Note: While waiting for step 6, you may need to restart IntelliJ. This step takes a long time, but it takes a long time the first time.