Getting psiTurk Installed on Your Computer

psiTurk can be installed on any modern computer which supports Python (<= 2.7). However, currently psiTurk is not supported on Windows (see below). It works well on most unix variants including Mac OS X, BSD, and Linux. Installation is usually not difficult.

When psiTurk is successfully installed, you will simply have a new command line tool available called psiturk. The psiturk command provides a number of functions to you including launching the server and interacting with the Mechanical Turk and Amazon Web Services (AWS) systems.

Installation requirements

Installation of psiTurk requires:

  1. A python installation (<= v2.7). We recommend the Enthought python distribution on Mac OS X.
  2. The ``pip`` package manager. Directions on installing this are given below.
  3. Access to a command line tool. (e.g., Terminal.app on Mac OS X)
  4. A web browser. A WebKit compatible browser such as FireFox, Safari, or Chrome is recommended.

An additional requirement for actually using psiTurk to run experiments is an Internet connected computer capable of receiving incoming requests.

Installation steps

To install the package there are two options currently. First, the current stable release of psiTurk is hosted on the python package index pypi. As a result, it can easily be installed as a standard python package using the python package manager tool pip. Alternatively, you can install directly from the development branch on github. The following instructions describe the general process. In addition, system specific notes are provided below.

Install stable version via pypi

The easiest way to install psiTurk is via pip. Linux users will likely prefer to install pip as described below. Otherwise, If you don’t already have pip, you can install it by typing the following in a terminal:

cd /tmp  # Just to put us in a directory that will be cleaned up periodically
curl -O https://raw.githubusercontent.com/pypa/pip/develop/contrib/get-pip.py
python get-pip.py  # If you get a permissions error, try typing sudo python get-pip.py

If you want a single system to run different versions of psiTurk (or other python packages) on a per-experiment basis, follow the Virtual Environment instructions below.

Once pip is installed, type into a terminal:

pip install psiturk

If this doesn’t work, try

sudo pip install psiturk

If the install was successful you will have a new command psiturk available on your command line. You can check the location of this command by typing

which psiturk

Install directly from github

You can also install the bleeding-edge development version directly from github using pip. To install the latest stable branch follow the instructions above to install pip and:

sudo pip install git+git://github.com/NYUCCL/psiTurk.git@master

If the install was successful you will have a new command psiturk available on your command line. You can check the location of this command by typing

which psiturk

Updating from a previous version

To avoid compatibility issues, if you upgrade from a previous version it can be useful to first uninstall then reinstall psiTurk using the following sequence of commands:

$ pip uninstall psiturk
$ git clone git@github.com:NYUCCL/psiTurk.git
$ cd psiTurk
$ sudo python setup.py install

Running inside a Virtual Environment

It can desirable to keep each of your experiments’ dependencies (python and python package versions) isolated from each other. For example, if you want to install the development version of psiTurk (as described above) in one experiment, but not all the others installed on your system, Virtual Environments provide a solution.

You can install via pip:

sudo pip install virtualenv virtualenvwrapper

And then start a new shell session. This will install the virtualenv tool as well as the supplementary virtualenvwrapper tools that make working with virtualenvs easier. You create a virtual environment as follows (if mkvirtualenv is not recognized follow the instructions here) :

$ mkvirtualenv my-experiment

Running virtualenv with interpreter /usr/bin/python2
New python executable in my-experiment/bin/python2
Also creating executable in my-experiment/bin/python
Installing setuptools, pip...done.

Then, at any point in the future, to activate the virtual environment use the workon command

$ workon my-experiment
(my-experiment) $ which python python pip easy_install

~/.virtualenvs/my-experiment/bin/python
~/.virtualenvs/my-experiment/bin/pip
~/.virtualenvs/my-experiment/bin/easy_install

As you can see, when the environment is active, running python or pip will run copies specific to your project. Any packages installed with pip or easy_install will be installed inside your my-experiment virtualenv rather than system-wide. Use the deactivate command to leave the virtualenv.

System-specific notes

Mac OS X

Apple users will need to install a C compiler via XCode; to do so, install XCode from the App store. Once you have downloaded it, install the command line tools from the preferences menu as instructed here. For earlier versions of Mac OS X (e.g., Snow Leopard) you may need to install XCode using the installation disc that came with your computer. The command line tools are an option during the installation process for these systems.

Linux

psiTurk is relatively painless to install on most Linux systems since all four of the requirements listed above come installed by default in most distributions.

If you encounter install problems when installing using pip as above, a likely cause is that you are missing the package from your distribution that contains a needed header file. In this case, one way to troubleshoot the problem is to do a web search for the name of your distribution and the name of the missing header file (which often appears in the error text produced by a failed pip install). That search will likely turn up the name of the package for your distribution that supplies the needed header file.

As an example, before installing psiTurk on a minimal Debian 7 server (such as the one provided by many server hosting companies) you will need to install some additional packages, as illustrated by the following example command:

aptitude install python-pip python-dev libncurses-dev

If you would like to use mysql as your backend database (which is optional, and can be done at any time), further packages are needed. On a Debian system, they are:

aptitude install python-pymysql python-sqlalchemy libmysqlclient-dev

If you have additional specific issues, or if you can report the steps needed to install psiTurk on a particular Linux distribution, please help us update the documentation!

Windows

psiTurk is currently not supported on Windows. This is due to a technical limitation in the ability to run server processes on Windows. However, there are a number of options to get around this (see below for details on each option):

Cloud-based install (experimental)

If your local computer does not support psiTurk is it still possible to use the package by using a free hosting solution such as openshift. Begin by creating an account at http://openshift.redhat.com/ and download the command line tools at https://www.openshift.com/developers/rhc-client-tools-install

Create a python-2.7 application and add a PostgreSQL cartridge to the app

rhc app create psiturk python-2.7 postgresql-8.4 --from-code git://github.com/jbmartin/psiturk-on-openshift.git

or you can do this to watch the build

rhc app create -a psiturk -t python-2.7
rhc cartridge add -a psiturk20 postgresql-8.4

Add this upstream psiturk repo

cd psiturk
git remote add upstream -m master https://github.com/jbmartin/psiturk-on-openshift.git
git pull -s recursive -X theirs upstream master

Then push the repo upstream

git push

That’s it, you can now checkout your application at

http://psiturk-$YOURNAMESPACE.rhcloud.com

To access the your openshift hosted database run

rhc port forward -a psiturk

Connect to the database using your favorite SQL app, the PostgreSQL Local specs, and your credentials.

Virtualization

You can install a program like VirtualBox on your pc. Programs like these are called hypervisors and emulate a computer within your computer. Your physical machine is called a host and the virtual machine is called a guest. This technique allows you to install a Linux guest regardless of what OS the host is running.

Virtualization requires some computing power from the host so this option is not recommended if your psiturk experiment requires a lot of computing power as well or if it’s is expected to have a lot of participants active at once. However, it is a good option to develop and test your psiturk experiments on Windows systems prior to Windows 10. If you are running Windows 10 or higher see below for the WSL option, which is much easier on your system than virtualization.

After you install the virtual machine software you need an installation image for a Linux based OS. You can choose any Linux distribution you like but Ubuntu is a good choice if you don’t know which one to pick. You can usually obtain an *.iso file for the Linux distribution you like. These are virtual cd-roms. You can load them into your virtual machine and begin installing the guest OS. Once that is complete you boot your virtual machine into Linux and follow the installation steps for Linux.

Windows Subsystem for Linux (WSL)

Windows now has the option to run a Linux translation layer inside Windows (WSL 1) or even a full Linux kernel (WSL 2). Either will allow you to run psiturk within the Linux subsystem. See https://docs.microsoft.com/en-us/windows/wsl/install-win10 for instructions on how to activate WSL on your system.

After you activate WSL and install a Linux distribution of choice as described you must make a small change to its configuration and install one or two libraries. Within the WSL environment create or edit the file /etc/wsl.conf. If you don’t know how to edit a file within WSL just run:

sudo nano /etc/wsl.conf

You will need to edit the file with admin rights (the sudo part of the command) which requires your WSL admin password. You chose the password when you installed WSL. This is a different password from your Windows admin or Windows user password! Add these contents to the file:

[automount]
options = "metadata"

If you used nano press control + X to exit. Nano will ask you to save the file. Choose Y for yes and exit. Editing this file enables file permissions to work as they do in Linux. This is needed when psiturk tries to read ~/.psiturkconfig. After you’re done editing wsl.conf exit all WSL windows and start a new one.

Most Linux distributions come with many libraries pre-installed, but WSL omits many of them. In a WSL window run these commands

sudo apt-get install libncurses5-dev
sudo apt-get install libpq-dev

The first one is needed for psiturk. The second one is optional and is only needed if you use a database other than sqlite. Run these commands next in a WSL window:

pip3 install psiturk
pip3 install psycopg2

If you get an error saying Command 'pip3' not found try replacing it with pip. If that still doesn’t work run sudo apt-get install python3 python3-pip. The first pip3 command installs psiturk itself. The second one is optional and again is only used if you use any database other than sqlite. Finally, create a file called ~/.psiturkconfig. You can use nano or any other text editor. You can enter your AWS and psiTurk access keys now or edit this file later. After you have created the file run this command

sudo chmod +rw ~/.psiturkconfig

This makes sure psiTurk is allowed to read the file. If you forget this step psiTurk will tell you the key is invalid but it really means it couldn’t read your config file. You only have to run this command once however, so if you’re sure you did it or just ran it again to be sure and psiTurk still tells you the keys are invalid then the keys really are invalid.

You should now be able to run psiTurk in the WSL environment. The status line will look a bit different since WSL doesn’t draw some box art characters properly but psiTurk will work just fine.