Windows installation#

Installing the developer version of PsyNet on a Windows machine depends on the “Windows Subsystem for Linux” (WSL). All code you run using your developer installation needs to be run within the Linux subsystem.

Step 0: Install WSL#

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 continuing. Then open your Ubuntu terminal and follow the instructions for the Linux developer installation.

Step 1: Perform Linux developer installation#

The following installation instructions apply to Ubuntu 20.04 LTS (Focal Fossa) only. They address both experiment authors as well as developers who want to work on PsyNet’s source code.

Note

You must have set up your GitLab SSH keys already.

Prerequisites#

Update and install required system packages#

sudo apt update
sudo apt upgrade
sudo apt install vim python3.10-dev python3.10-venv python3-pip redis-server git libenchant1c2a postgresql postgresql-contrib libpq-dev unzip

Install Python#

PsyNet requires a recent version of Python 3. To check the minimum version of Python required, look at PsyNet’s `pyproject.toml<https://gitlab.com/PsyNetDev/PsyNet/-/blob/master/pyproject.toml?ref_type=heads>`_ file, specifically at the line beginning with requires-python, and see which version of Python is required. To see the current version of Python 3 on your system, enter python3 --version in your terminal. If this version is lower than the minimum version specified in pyproject.toml, you should update your Python. The easiest way to do this is via the apt install command above, for example sudo apt install python3.10-dev for Python 3.10.

Install Docker and Docker plugins#

sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
   "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
   "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install docker.io docker-compose-plugin docker-buildx-plugin

Install Google Chrome#

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list'
sudo apt update
sudo apt install google-chrome-stable

Setup PostgreSQL#

sudo service postgresql start
sudo -u postgres -i

createuser -P dallinger --createdb

Password: dallinger

createdb -O dallinger dallinger
createdb -O dallinger dallinger-import
exit

sudo service postgresql reload

Install heroku client#

curl https://cli-assets.heroku.com/install-ubuntu.sh | sh

Install Python virtualenv#

pip3 install virtualenv
pip3 install virtualenvwrapper

Setup virtual environment#

export WORKON_HOME=$HOME/.virtualenvs
mkdir -p $WORKON_HOME
echo "export VIRTUALENVWRAPPER_PYTHON=$(which python3)" >> ~/.bashrc
echo "source ~/.local/bin/virtualenvwrapper.sh" >> ~/.bashrc
export VIRTUALENVWRAPPER_PYTHON=$(which python3)
source ~/.local/bin/virtualenvwrapper.sh
mkvirtualenv psynet --python $(which python3.10)

In case you experience problems setting up the virtual environment:

  • Check in which directory virtualenvwrapper.sh is installed. This might be a different directory than ‘~/.local/bin/’. In that case, adapt the code above to source this file accordingly.

  • Check whether the directory where virtualenvwrapper.sh was installed is added to PATH. If not, add the directory to PATH.

Activate virtual environment#

workon psynet

Dallinger#

Install Dallinger#

In the example below Dallinger is cloned into the user’s home directory, but you can choose a different location to put your installation, like e.g. ~/cap.

Note

Make sure you have activated your virtual environment by running workon psynet.

cd ~
git clone https://github.com/Dallinger/Dallinger
cd Dallinger
pip install -r dev-requirements.txt
pip install --editable '.[data]'

Verify successful installation#

dallinger --version

PsyNet#

Install PsyNet#

In the example below PsyNet is cloned into the user’s home directory, but you can choose a different location to put your installation, like e.g. ~/cap.

Note

  • Make sure you have added an SSH Public Key under your GitLab profile.

  • Also, make sure you have activated your virtual environment by running workon psynet.

cd ~
git clone git@gitlab.com:PsyNetDev/psynet
cd psynet
pip install --editable .

Verify successful installation#

psynet --version

As an experiment author you are now done with the installation and you can begin building experiments.

As a developer who wants to work on psynet’s source code, however, please continue with the remaining installation steps below.

Note

Below instructions apply to developers only.

Install ChromeDriver#

Needed for running the Selenium tests with headless Chrome.

wget https://chromedriver.storage.googleapis.com/109.0.5414.74/chromedriver_linux64.zip --directory /tmp
sudo unzip /tmp/chromedriver_linux64.zip chromedriver -d /usr/local/bin/

Install additional Python packages#

pip install -e '.[dev]'

Install the Git pre-commit hook#

With the virtual environment still activated:

pip install pre-commit

This will install the pre-commit package into the virtual environment. With that in place, each git clone of psynet you create will need to have the pre-commit hook installed with:

pre-commit install

This will install the pre-commit hooks defined in .pre-commit-config.yaml to check for flake8 violations, sort and group import statements using isort, and enforce a standard Python source code format via black. You can run the black code formatter and flake8 checks manually at any time by running:

pre-commit run --all-files

You may also want to install a black plugin for your own code editor, though this is not strictly necessary, since the pre-commit hook will run black for you on commit.

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’…