Setting up Docker

The instructions below describe how to set up an environment for developing WA services in Docker on your local machine.

Linux

To start developing on Linux, you'll need to pull the World Avatar repository, install Docker, and install docker-compose. The process differs slightly between distributions; the instructions below apply to CentOS 7 and CentOS 8.

Clone the World Avatar repository and configure git

• Git is preinstalled on most Linux distributions; if it isn't, install it using your package manager
• Clone the repository to a location of your choice, e.g.

mkdir ~/code && cd ~/code
git clone https://github.com/cambridge-cares/TheWorldAvatar.git

• Set your username and email in the global git configuration

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "MY_NAME@example.com"

Install Docker

• Point your package manager to an appropriate repository and install Docker:

CentOS 7:

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io

CentOS 8:

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io

• Start the Docker daemon and have it auto-start on reboot

  sudo systemctl start docker
  sudo systemctl enable docker

• Give non-root users access to the Docker daemon where necessary

  sudo usermod -a -G docker <username>

Install docker-compose

Docker-compose can be installed by running a script in the World Avatar repository:

  sudo <repository_root>/Deploy/scripts/install_docker-compose.sh

Windows

The recommended approach to developing with Docker on Windows is to use Windows Subsystem for Linux 2 (WSL2). This involves storing and running your code within a Linux environment, but can be set up in a way that minimises the pain for developers who are only used to Windows.

The instructions below describe how to get Docker running with WSL2. Note that Windows 10 version 1903 (released 21/05/2019), or later, is required.

Install and Configure WSL2

• Follow the steps here. When it comes to choosing a distribution, any should work with these instructions, but they were tested using Ubuntu-20.04. When the distro has finished downloading, be sure to click "Launch" to finish the installation and set a username and password. You can then close the WSL terminal.

Set the default WSL distribution

You can check that the distribution you just installed is set as the default by running the following in a Windows cmd terminal:

  wsl --list

• If "(Default)" doesn't already appear after the distribution name, run

  wsl -s <distro>

(e.g. wsl -s Ubuntu-20.04)

Clone the WA repository and configure git

• Open the app for your Linux distribution (it should appear under "Recently added" in the Windows start menu)
• Clone the World Avatar repository to a location of your choice and checkout the main branch. e.g.:

mkdir ~/code && cd ~/code
git clone https://github.com/cambridge-cares/TheWorldAvatar.git -b main

• Set your username and email in the global git configuration

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "MY_NAME@example.com"

WSL configuration options

One issue that seems fairly common is that, without additional configuration, WSL2 can consume a very large fraction of the system memory. To prevent this, create the file %UserProfile%\.wslconfig and add the following to it:

[wsl2]
memory={N}GB
swap=0
localhostForwarding=true

Choosing {N}=6 on a machine with 8GB RAM has worked well for others. To apply the changes, restart the Windows service called 'LxssManager'.

Install Docker Desktop

• Follow the instructions here. Ensure "Install required Windows components for WSL2" is ticked in the installer.
• Remember to start Docker Desktop after installing. Docker and docker-compose are now installed.

Troubleshooting

• If issuing Docker commands inside WSL gives errors like

docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

open the Docker Desktop settings, choose 'Resources' then 'WSL INTEGRATION' and ensure integration is turned on for your distribution of choice.

Install and Configure VS Code

While it's possible to edit code using Linux editors and run Docker from the command line at this stage, we strongly recommend using VS Code instead. It runs in Windows, but connects to your WSL distribution 'remotely' to allow you to develop code, manage git repositories and run Docker all from a single IDE. To install it:

1. Download and install VS Code from here
2. Open the software, go to 'Extensions' (Click the building blocks icon, or use Ctrl-Shift-x) and install the "Remote - WSL" extension.
3. Connect to your WSL distribution
4. Open the "Command Palette" by going to View/Command Palete" (or Ctrl-Shift-p)
5. Type "wsl" to narrow down the options, then choose "Remote-WSL: New Window"
6. Open a folder of your choice (e.g. ~/code/TheWorldAvatar) to start developing