Installing PsyNet via Docker (Windows)

Step 0: Install WSL

Docker on Windows depends on the “Windows Subsystem for Linux” (WSL). All code you run using PsyNet and Docker needs to be run within the Linux subsystem. If you haven’t worked with Docker before you may well need to install this.

Here is a simple tutorial for installing WSL 2 and Ubuntu on Windows: https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-11-with-gui-support#1-overview. Note: it is WSL 2 we want, not just WSL. Bear this in mind when looking for online tutorials.

WSL is a platform for installing particular Linux operating systems. In addition to installing WSL, the above tutorial also installs Ubuntu, which is a particular flavor of the Linux operating system. This is important for getting Docker to work.

Once you’ve installed Ubuntu, it’s important that you select it as the default distro within WSL. You can list available distros within WSL by running the following command in your terminal:

wsl -l --all

You want to set your default to the Ubuntu option. That probably means writing something like this:

wsl --setdefault Ubuntu

Note: If you see a message beginning “Hardware assisted virtualization and data execution protection must be enabled in the BIOS”, you need to restart your computer into BIOS and change some settings to enable those two things. The precise set of steps will depend on your computer. The first step though is to restart your computer, and press a certain key to launch into BIOS – ordinarily that key will be printed on the screen at some point during the startup sequence. Hint – you might find that the option you need to select is called ‘SVM mode’….

Once you’ve installed WSL, you probably will need to restart your computer before trying to relaunch Docker Desktop.

Step 1: Install Docker Desktop

You can get Docker Desktop from the following link: https://www.docker.com/products/docker-desktop/ Normally Docker Desktop will work out of the box on Linux and macOS machines, but there is lots of help available online if you get stuck.

You may need to set some settings in Docker Desktop once it’s installed. Navigate to Docker Desktop settings, then look for an ‘Advanced’ tab. If you don’t see such a tab, you can skip the following instructions. If you do see such a tab, do the following:

1. Select ‘System (requires password)’ installation of Docker’s CLI tools, rather than ‘User’.

2. Tick the box that says ‘Allow the default Docker socket to be used’.

3. Tick the box that says ‘Allow privileged port mapping’.

If you are on a Mac that uses Apple Silicon (i.e. most new Macs since 2021…?) then you should go to Preferences and tick the box that says ‘Use Rosetta for x86/amd64 emulation on Apple Silicon’. If you don’t tick this box PsyNet will run very slowly.

Step 2: Install PyCharm

We recommend using PyCharm as your integrated development environment (IDE) for working with PsyNet. You can learn about PyCharm here: https://www.jetbrains.com/pycharm/ For proper integration with PsyNet (especially if you are using the Docker installation route), you will need to use the Professional version in particular. If you are a student or academic, you can get a free educational license via the PyCharm website.

Warning

Windows users only: You should configure PyCharm to use Unix-style line endings (LF) by default instead of Windows-style line endings (CLRF); otherwise your Docker scripts may not run. To do this, follow these instructions from the JetBrains website:

1. Open PyCharm’s settings.

2. Go to File | New Projects Setup | Settings (or Preferences) for New Projects | Editor | Code Style.

3. Set Line separator to ‘Unix and macOS (n)’.

4. If you are in a project already, you may wish to select the current project from the Scheme dropdown menu on this same page and repeat the process of setting the line seperator.

5. Press OK.

Step 3: Install Git

Most people working with PsyNet will need to work with Git. Git is a popular system for code version control, enabling people to track changes to code as a project develops, and collaborate with multiple people without accidentally overwriting each other’s changes. To install Git, visit the Git website.

You will also typically work with an online Git hosting service such as GitHub or GitLab. Speak to your lab manager for advice about which one your lab uses; at the Centre for Music and Science we use GitHub, whereas the Computational Auditory Perception group uses GitLab. You will probably want to create an account on that website before continuing.

Warning

Windows users only: once you’ve installed Git, you need to run a few commands in your terminal:

git config --global core.autocrlf false
git config --global core.eol lf

This code tells Git to use Unix-style line endings in your code repositories rather than Windows-style line endings. This is important because your Docker run scripts won’t run with the latter.

Warning

Windows users only: if you plan to use an SSH key to connect to your online Git hosting service, and you want to use an SSH key with a password, then by default you will have to reenter your password each time you restart WSL. If this sounds annoying, we recommend either creating your SSH key without a password, or following the instructions here to have you password managed by ssh-agent.

Step 4: Download an experiment

To check that everything is now running properly, you should try running an experiment. You can start by downloading one from the Example experiments page.

The easiest way to download the code is as a zip file. If you are viewing the repository online you should see a link to do this on the web page.

If you want to work on the experiment yourself you should probably download it using Git. If you are viewing the repository online you should see button saying ‘Clone’ or similar; this will give you some download links to copy. You can use these in your terminal. We recommend you use the ‘HTTPS’ link.

# Navigate to the parent directory where you want to download your project.
# The project will be downloaded as a subdirectory within this directory,
# defaulting to the name of the repository.
# Note: you should create the parent directory first if it doesn't exist yet.
cd ~/Documents/psynet-projects

# Clone the Git repository, replacing the URL below with the one you get from
# the website under the Clone with HTTPS option.
git clone https://gitlab.com/pmcharrison/example-experiment.git

If you want to run an experiment from a private repository then someone should have added you already as a collaborator. You will need to use your credentials when cloning the repository; if you use the HTTPS link then you should be prompted for these automatically.

Step 5: Set up PyCharm

The first time you open PyCharm you may need to enter some license information, decide to start a free trial, or something similar. Do this first.

Now, within PyCharm, click File > Open and open the folder that Git downloaded for you. This opens the experiment directory as a PyCharm ‘project’. It may ask you to setup an ‘interpreter’ at this point; ignore this message and click Cancel.

The first thing you should do is ‘build’ the experiment. The first time you build a PsyNet experiment it will download PsyNet and lots of other dependencies. Make sure you have a good internet connection for this, it will take a few minutes. You build the experiment by running the following in your PyCharm terminal:

bash docker/build

Note: if you see an error message like this:

./docker/run: Permission denied

run the following command, then try again:

chmod +x docker/*

If you see other error messages at this point, see Troubleshooting.

Now you should configure PyCharm to use your experiment’s Docker image.

Warning

If you are not using PyCharm Professional Edition, you will probably not have the option to integrate PyCharm with Docker in this way.

To do this, first open the Dockertag file in your experiment’s directory (this is simply a file with the filename ‘Dockertag’), and copy the contents to your clipboard. Then look for the ‘interpreter’ box in the bottom-right corner of your screen; this would normally say ‘No interpreter’, but it could say something like ‘Python 3.11’. Click on this text and click ‘Add New interpreter’, then click ‘On Docker’. Select an option that looks like ‘Pull, or perhaps ‘Pull or use existing’, then under ‘Image tag’ paste the contents of the Dockertag file you copied earlier. Click Next, and wait a while. The script will initially look for that tag on Dockerhub, which should fail; It should then look for that tag on your local computer, and successfully acquire the image you just built locally. Click Next, then select ‘System Interpreter’, then click ‘Create’. You should have now successfully set up your interpreter.

Step 6: Running the experiment

Warning

MacOS users only:

macOS’s ‘AirPlay Receiver’ functionality clashes with the default ports used by Dallinger and PsyNet. You should disable this functionality before proceeding. To achieve this, go to System Preferences, then Sharing, and then untick the box labeled ‘Airplay Receiver’.

You should now be able to run the experiment. Try this by running the following command in your PyCharm terminal:

bash docker/psynet debug local

It’ll print a lot of stuff, but eventually you should see ‘Dashboard link’ printed. Open the provided URL in Google Chrome, and it’ll take you to the experiment dashboard. From here you can start a new participant session.

Step 7 (Optional): Install editable PsyNet and Dallinger repositories

Sometimes it is useful to edit PsyNet and Dallinger source code as part of debugging an experiment. To do this, you should git clone the PsyNet and Dallinger repositories from their corresponding hosts:

• https://gitlab.com/PsyNetDev/PsyNet

• https://github.com/Dallinger/Dallinger/

You should place these repositories in your working directory, and leave their names exactly as their defaults (‘PsyNet’ and ‘Dallinger’). If you are using a Windows machine, then you will need to place these repositories in your WSL (Linux) working directory. You may be able to find this by going to File Explorer, looking for Linux, then Ubuntu. If you are not sure, try running the command below, and it should print an error message telling you where exactly to look.

Now, if you run an experiment using the following command:

bash docker/psynet-dev debug local

it will use these local repositories for PsyNet and for Dallinger.

Troubleshooting

WSL 2 installation is incomplete

If you see a message beginning with “WSL 2 installation is incomplete”, you probably need to do the following:

• Click on the link it gives you

• Click on the link under ‘download the latest package’, open and run the installer once it has downloaded

• Continue with the next steps of the installation

• Note: if you run Powershell, it might fail if you run it on admin mode! If you get stuck (Access Denied), try running it again without admin mode and see if it works.

Hardware assisted virtualization

If you see a message beginning “Hardware assisted virtualization and data execution protection must be enabled in the BIOS”, you need to restart your computer into BIOS and change some settings to enable those two things. The precise set of steps will depend on your computer. The first step though is to restart your computer, and press a certain key to launch into BIOS – ordinarily that key will be printed on the screen at some point during the startup sequence. Hint – you might find that the option you need to select is called ‘SVM mode’…

Failed to solve with frontend dockerfile

If you see a message starting “failed to solve with frontend dockerfile.v0”, you may want to try rebooting your computer and trying again.

Invalid option name: pipefail

If you see an error message like this when running a Docker command:

command not found 2:
command not found 4:
invalid option name: set: pipefail

The problem is probably that your project has the wrong line endings; on Windows, if you are not configured correctly, then your files may end up with Windows-style line endings (CRLF) instead of Unix-style line endings (LF). To fix this, first follow the line-endings instructions described above for setting up Git and PyCharm in Windows. Then select your project folder in the project pane, and from the task bar select File | File Properties | Line Separators | LF - Unix and MacOS. Your command should now run without the error.

A timeout occurred

When starting Docker for Windows you might run into following error: “A timeout occured while waiting for a WSL integration agent to become ready”. In that case, you may want to try installing an older version of Docker Desktop (e.g. 4.17.1).