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.
You must have set up your GitLab SSH keys already.
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
PsyNet requires a recent version of Python 3. To check the minimum version of Python required,
look at PsyNet’s
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
sudo service postgresql start sudo -u postgres -i
createuser -P dallinger --createdb
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#
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.
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#
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.
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 firstname.lastname@example.org:PsyNetDev/psynet cd psynet pip install --editable .
Verify successful installation#
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.
Below instructions apply to developers only.
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:
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.
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’…