cpllab/psiturk repository overview

⁠Version-stable psiTurk Docker images

This repository provides Docker images for psiTurk, via DockerHub⁠.

According to the documentation⁠, psiTurk is:

⁠Tags

The images are tagged using psiTurk version numbers, as well as the tag latest for the most recent version of psiTurk available on PyPI⁠ and dev for the most recent version of psiTurk available on the master branch of the psiTurk repository⁠. The current tags are:

• dev
• latest
• 2.2.3
• 2.2.2
• 2.2.1
• 2.2.0
• 2.1.7
• 2.1.6
• 2.1.4

It's likely that you'll want to use either the latest or dev tag. The dev tag is often quite a bit further along than the latest release on PyPI⁠. In particular, at the time of writing (2018-07-28), if you want to use a recent version of MySQL for your database, you'll need to use the dev tag, since the latest tag for the version of psiTurk that is on PyPI uses a very outdated version of SQLAlchemy, which only supports MySQL versions 5.7.x and older. If you want to use an 8.x.y version of MySQL, you'll need to use the dev tag.

Also note that there is not a tag for 2.1.5 because there is not a version for psiTurk 2.1.5 on PyPI⁠. All other older versions of the 2.x.y series are not available because they try to install gnureadline, which requires installing libncurses5-dev via apt-get⁠, and I'd rather not increase the image size just for some older psiTurk versions that folks are unlikely to want to ever use. None of the 1.x.y versions are available because none of these support the Ad Server⁠.

It's worth noting that us_only and approve_requirement did not work prior to version 2.2.0 (see, e.g., here⁠). Use older versions at your own risk.

⁠Usage

These Docker images are intended to be the base for your own (very simple!) Docker images. (For help using psiTurk and Docker together, as well as integrating a database, check out this series of blog posts that I wrote⁠ on this very topic.)

To get started, first install Docker⁠.

Next, create a directory for your experiment:

mkdir stroop-task
cd stroop-task

Then, create a Dockerfile (replace latest with whatever version of psiTurk that you want to use; see the available tags above⁠):

echo "FROM adamliter/psiturk:latest" > Dockerfile

You have two options about how to set up your Docker image. You can not include the experiment files in the image and instead keep the experiment files on the host machine, mounting the directory containing the experiment files to the Docker container.

Alternatively, you can include the experiment files in the Docker image itself.

With the first option, you will be able to edit the files on your local host machine, and these changes will be reflected in the experiment that is being served by the Docker container without having to rebuild the image. I'd suggest this option for developing and tweaking an expeirment.

With the second option, the files are copied into the Docker image, and so the Docker image has to be rebuilt each time you make a change to the experiment files. I'd suggest this option for deployment of the final version of your experiment and/or distributing it to other researchers.

In either case, let's use the example experiment generated by running the command psiturk-setup-example. So, run the command:

psiturk-setup-example

This will create a directory called psiturk-example with the example experiment files. Unless you already have a ~/.psiturkconfig file, it most likely also created this file, too.

The Docker image expects the .psiturkconfig file to be inside the same directory as the experiment files, so run the following command:

mv ~/.psiturkconfig ./psiturk-example/

⁠Mounting a volume

Now, to set up your Dockerfile for the first option, run the following command:

echo 'VOLUME ["/psiturk"]' >> Dockerfile

Then, build your Docker image:

docker build -t <YOUR_USERNAME>/stroop-task .

And, finally, run a container from the built image:

docker run -it --rm --name stroop-task -p 22362:22362 -v `pwd`/psiturk-example:/psiturk <YOUR_USERNAME>/stroop-task

This will pop you into a bash session where you can start the psiTurk server:

psiturk
server on

To check it out, navigate to http://localhost:22362 in your browser.

To detach from the Docker container without killing it, hit CTRL+p then CTRL+q.

Now you can edit your experiment files, and these changes should be reflected in your browser.

⁠Including experiment files in image

To set up your Dockerfile for the second option, run the following command:

echo "COPY ./psiturk-example /psiturk" >> Dockerfile

Then build your Docker image:

docker build -t <YOUR_USERNAME>/stroop-task .

And, finally, run a container from the built image:

docker run -it --rm --name stroop-task -p 22362:22362 <YOUR_USERNAME>/stroop-task

This will pop you into a bash session where you can start the psiTurk server:

psiturk
server on

To check it out, navigate to http://localhost:22362 in your browser.

If you want to make any changes, you will have to rebuild the image because the experiment files are inclued in the image.

⁠Troubleshooting

If you're having trouble getting things to work, try changing the default host setting in config.txt from localhost to 0.0.0.0. For some reason, the localhost option has never worked for me, but 0.0.0.0 does.