Windows setup

All the instructions in the README and the scripts run by the dev-env itself assume that you will be using a Linux-like command line environment. For Windows, Git For Windows or Windows Subsystem for Linux will provide that.

After extensive testing, here are several configurations that work with most or all dev-env features. All testing was done in Windows 10, although the Git Bash and Vagrant options may work with Windows 7.

Windows Subsystem for Linux 2

It should "just work", with Docker Desktop's WSL2 integration turned on, and Ruby/Git installed via your distro's package manager or whatever mechanism you prefer.

Windows Subsystem for Linux 1

Ubuntu is the suggested distribution. Note that due to an SSH forwarding bug, if your Windows 10 version is 1803 or earlier, you should use Ubuntu 16.04 (there is a specific entry for it in the store). If you are on Windows 10 1809 to 20H1, then Ubuntu 18.04 is recommended (20.04 has compatibility issues with WSL1). Windows 10 20H2 onwards can use the latest.

• If using Ubuntu, native Linux Git will already be present; otherwise it can be installed it using your distro's package manager.

• Install the native Linux Ruby using your distro's package manager or rbenv. Make sure ruby --version returns at least version 2.5.

• The native Linux Docker daemon won't run in WSL1, so you need still need to use Docker for Windows. There are two ways of allowing docker and docker-compose commands to work in the WSL terminal:

  Option 1 (recommended) - Linux Docker CLI connecting to Windows daemon via TCP

  Follow the instructions on this page. You will end up with the Linux Docker and Docker-compose applications installed, connecting over TCP to the Windows daemon.

  Option 2 - Symlinks to the Windows Docker executables

  Only do this if Option 1 isn't viable, e.g. you don't want to open up your Docker on a TCP port or change your volume mount locations.

  It will not work with any command that needs a tty such as the bashin alias. You'll need to use a different shell for them (even normal Windows cmd) and run the raw docker command (e.g. docker exec -it containername bash), not the aliases.

  Simply create the symlinks like so:

  • sudo ln -s '/mnt/c/Program Files/Docker/Docker/resources/bin/docker.exe' /usr/local/bin/docker
  • sudo ln -s '/mnt/c/Program Files/Docker/Docker/resources/bin/docker-compose.exe' /usr/local/bin/docker-compose

Git Bash

Use the Ruby Windows installer. It should have modified your PATH environment variable, so ruby --version returns something in Git Bash.

Docker for Windows should also have modified your PATH environment variable, so docker --version returns something in Git Bash.

It will not work with any command that needs a tty such as the bashin alias. You'll need to prefix the command with winpty and also use the raw docker command instead of the alias, e.g. winpty docker exec -it containername bash.

Warning! Since you'll be using the Windows Git, but your applications will (probably) be executing in Linux containers, you need to make sure file line endings don't get transformed to Windows style during cloning, otherwise shell scripts may have issues executing in the containers. This can be achieved by setting autocrlf to false globally, or on a per repo basis with .gitattributes.

Vagrant / VirtualBox

A Vagrantfile is provided which will, upon vagrant up, create a CentOS (Linux) virtual machine containing all the prerequisites. This effectively takes Windows out of the equation entirely, although does come with the side effects you'd expect from introducing another layer (making it harder to directly access the individual containers from Windows-based tooling, for example).