2. Prerequisites

Slurk was developed and tested on UNIX-systems only. We therefore recommend using it on such or using WSL for Windows. The easiest way to use the system is using Docker. For this, docker is recommended.

If you are operating on Ubuntu, then follow Install docker into Ubuntu
If you are operating on Windows 10, then follow Prepare Windows 10

For other operating systems, please see the official docker documentation.

2.1. Prepare Windows 10

Docker cannot easily run on Windows by default. Thus we enable the Windows Subsystem for Linux. Make sure that Windows 10 has the latest updates installed:

For x64 systems: Version 1903 or higher, with Build 18362 or higher.
For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.

Note

This guide follows the official WSL2 documentation, so have a look into these for more details. These instructions use experimental features for Docker on Windows and thus could be outdated at any time. Furthermore, this guide is a response to a Problem with getting an admin token (Ubuntu on WSL).

2.1.1. Setting up WSL 2

Type “PowerShell” into the search field. Right-click on the Windows PowerShell and then select run as administrator.
Enable WSL with the following command:

$ dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Upgrade to WSL2 with the following command:

$ dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart the system
Download the Linux Kernel update package
Double-click the update package downloaded in the previous step. Follow the installation steps.
(Optional) If step 6 results in an error update only applies to machines with the Windows subsystem for Linux: Type into the search field “Turn Windows features on or off”. Open the program. Deselect Virtual Machine Platform and Windows Subsystem for Linux and click OK. Restart your system. Open the program again and this time select Virtual Machine Platform and Windows Subsystem for Linux and click OK. Restart your system. Try running step 6 again.
Set WSL2 as the default for linux distributions:

$ wsl --set-default-version 2

2.1.2. Install Ubuntu-20.04.1 using the App Store

After the installation is complete click Launch
Set a Unix username and password
Open a Powershell
Check the used WSL version for each distribution using PS:

$ wsl --list --verbose
NAME                   STATE           VERSION
Ubuntu-20.04           Running         2

Open a shell for the Ubuntu sub-system and follow the Install docker into Ubuntu guide.

2.2. Install docker into Ubuntu

Note

This guide follows the official docker documentation, so have a look into these for more details.

Uninstall old versions:

$ sudo apt-get remove docker docker-engine docker.io containerd runc

Install docker using the repository:

$ sudo apt-get update
$ sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common

Add Docker’s official GPG key:

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Use the following command to set up the stable repository:

$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

Install the docker engine:

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io

2.3. Potential after-installation steps

Start the docker daemon manually (if not already started):

$ sudo service docker status
$ sudo service docker start

Add the non-root user to the docker group:

$ sudo groupadd docker
$ sudo usermod -aG docker ${USER}

Re-login.

Verify that you are part of the docker group:

$ groups $USER

Verify that Docker Engine is installed correctly (should print an informal message and exit):

$ docker run hello-world

2.4. Checkout slurk

Warning

WSL users need to checkout the project using the WSL otherwise the line-endings are not correct!

Generate a ssh key pair (with defaults):

$ ssh-keygen

Upload or copy the generated public key to your github SSH settings
Clone the repository:

$ git clone git@github.com:clp-research/slurk.git

Go into the slurk top directory.

2.5. Run with docker (recommended)

Go into the slurk top directory. Build your slurk docker image:

docker build --tag "slurk/server" -f Dockerfile .

Start the server:

$ export SLURK_DOCKER=slurk
$ scripts/start_server.sh
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Fetch the admin token:

$ scripts/read_admin_token.sh
01234567-89ab-cdef-0123-456789abcdef

(Optional) In case the output of the above script is empty, you may find valuable information in the logs:

$ docker logs $SLURK_DOCKER

2.6. Run without docker

(Optional) Create and activate a virtual environment (with Python 3.9).

With Miniconda or Conda:

$ conda create -n slurk python=3.9
$ conda activate slurk

With venv:

$ python3 -m venv slurk
$ source ./slurk/bin/activate

Install dependencies:
$ pip install -r requirements.txt

Start the server and get the admin token:

$ scripts/start_server.sh
[INFO] Starting gunicorn 20.1.0
[INFO] Listening at: http://0.0.0.0:5000 (1232)
[INFO] Using worker: geventwebsocket.gunicorn.workers.GeventWebSocketWorker
[INFO] Booting worker with pid: 1233
admin token:
01234567-89ab-cdef-0123-456789abcdef

2.7. Side-notes

The installation of the docker-ce using the WSL showed “failures”, but these seem not to have an impact on the docker engine.

Setting up docker-ce-cli (5:19.03.13~3-0~ubuntu-focal) ...
Setting up pigz (2.4-1) ...
Setting up cgroupfs-mount (1.4) ...
invoke-rc.d: could not determine current runlevel
Setting up grub2-common (2.04-1ubuntu26.4) ...
Setting up grub-pc-bin (2.04-1ubuntu26.4) ...
Setting up docker-ce (5:19.03.13~3-0~ubuntu-focal) ...
Created symlink /etc/systemd/system/multi-user.target.wants/docker.service → /lib/systemd/system/docker.service.
Created symlink /etc/systemd/system/sockets.target.wants/docker.socket → /lib/systemd/system/docker.socket.
invoke-rc.d: could not determine current runlevel
Setting up grub-pc (2.04-1ubuntu26.4) ...

Creating config file /etc/default/grub with new version
Setting up grub-gfxpayload-lists (0.7) ...
Processing triggers for install-info (6.7.0.dfsg.2-5) ...
Processing triggers for libc-bin (2.31-0ubuntu9) ...
Processing triggers for systemd (245.4-4ubuntu3.2) ...
Processing triggers for man-db (2.9.1-1) ...
Processing triggers for linux-image-unsigned-5.6.0-1028-oem (5.6.0-1028.28) ...
/etc/kernel/postinst.d/initramfs-tools:
update-initramfs: Generating /boot/initrd.img-5.6.0-1028-oem
W: mkconf: MD subsystem is not loaded, thus I cannot scan for arrays.
W: mdadm: failed to auto-generate temporary mdadm.conf file.

This is discussed in the following issue:

microsoft/WSL#4903 (mdadm 4.1-2 causes unrecoverable grub config loop in dpkg, apt) Spiritually similar #4763 (over there it was LVM). WSL2 does not load the Linux kernel with GRUB (and WSL1 doesn’t load a Linux kernel at all). Linux RAID (mdadm) isn’t applicable for lack of Multiple Disks. Somehow those were installed on your system. Purging those packages should help.