Link Search Menu Expand Document

Serving experiments

Table of contents

  1. Log onto the server
  2. Copy your experiment onto the server
  3. Configure your experiment
    1. Set the secret key
    2. Turn off debug mode
    3. Set completion codes (Prolific only)
  4. Start a detached screen
  5. Serve your experiment
    1. Identify an open port
    2. Start the gunicorn server
    3. Accessing the experiment
  6. Closing your experiment
    1. Closing a screen instance
    2. Killing an orphaned process
  7. Copy data off the server

Log onto the server

PNI virtual machines (Niv / Daw labs only)

In the Niv & Daw labs, we have several virtual machines (VMs) available for the purpose of running online experiments. To log onto a VM, open a terminal and SSH in:

ssh <user-name>@<server-name>

For security reasons, we will not list the server names here. Please ask an administrator (e.g., Sam or Dan) for the server names. Note: you need to be on the Princeton VPN to access the VMs.

All other users

Log onto your server as normal.

Copy your experiment onto the server

From Github

If you are hosting your code on Github, you can clone your experiment directly onto the server by running the following command from the server:

git clone <repo-url>.git

From your local machine

If your code is only available on your local machine, you can copy over your experiment with the following command from your local machine:

scp -r <path-to-local-directory> <user-name>@<server-address>:<path-to-new-directory>

See here for a detailed explanation of the command above.

Configure your experiment

Before launching your experiment, you need to modify the NivTurk configuration file (app.ini).

Set the secret key

Set a secret key in the configuration file (Line 5). The secret key can be a random string of alphanumeric characters (e.g. from The key encrypts cookies so that they cannot be read by participants (though this is not foolproof; see here).

Reusing secret keys across NivTurk applications can result in unexpected errors. Be sure to use a new key for each experiment.

Turn off debug mode

Turn off debug made in the configuration file (Line 9). This is accomplished by setting DEBUG = false. This prevents cookies from being reset on every new page visit (for details see here).

Set completion codes (Prolific only)

If you are running your experiment on Prolific, set the completion code (Line 15). This code should be provided to you by Prolific (for details see here). You may also change the dummy code (Line 19) though this is not required.

Start a detached screen

One issue with running experiments on the servers is that, if you lose connection to the server for any reason, the serving process may be interrupted mid-experiment. One way to prevent this is to use “detached” terminal sessions that will remain online even if you disconnect from the server.

To start a “detached” session, run the following command while logged onto the virtual machine:

screen -S <session-name>

This will start a new terminal session. From here, follow the steps below to serve an experiment. When the experiment is online, you will be free to close the terminal (i.e. quit the terminal application); the “detached” session will stay online even if you quit!

Upon next logging onto the virtual machine, you can reconnect to the session by running:

screen -r

Instead of screen, you may also use tmux. See here for a tutorial.

Serve your experiment

Identify an open port

Before you serve an experiment, you must first identity an open port on which to host the experiment. The PNI virtual machines have 10 ports configured for serving experiments (ports 9000-9010).

To check which ports are in use, you can check using the netstat utility:

netstat -plnt | grep ':90*'

Any ports that are returned by the command above are ports currently in use and therefore unavailable for you to use. If a port is not listed, it is free.


In the example above, you can see that port 9001 is in active use and unavailable for others to use.

Start the gunicorn server

Once you have identified a port to use, you are ready to serve your experiment. We use gunicorn as our web server client for serving experiments over the web.

First, if applicable, source your NivTurk python environment:

source activate nivturk

Next, serve the experiment by running the following command from inside the NivTurk folder:

cd <nivturk-folder>
gunicorn -b -w 4 app:app

The -b argument specifies the host and port (e.g. port 9000). The -w argument configures how many workers gunicorn will run. In general, four workers should be sufficient to handle hundreds to thousands of requests per second (for discussion, see here). Finally, app:app specifies which application to load.

Accessing the experiment

For Niv lab users: With the web server running, you (or a participant) should be able to reach the experiment by navigating to:

# for Prolific

# for MTurk

For all others: With the web server running, you (or a participant) should be able to reach the experiment by navigating to:

# for Prolific

# for MTurk

For testing purposes, you will need to provide a dummy ID so that NivTurk lets you continue.

To check the IP address of the server, run the following command:

curl; echo

To note, the URL arguments workerId and PROLIFIC_PID are not strictly necessary to reach the page. However, without these the application will automatically redirect a user to the error page.

To note, there are several additional URL arguments (e.g. task ID) that the NivTurk will normally receive from the recruitment website. However, if these arguments are absent NivTurk will not prevent the user from progressing.

Closing your experiment

When you are finished collecting data, it is important to close down your gunicorn instance in order to free up its port for other experimenters (and to minimize security risks).

Closing a screen instance

If you have gunicorn running in a detached screen, you can reconnect to a previous screen session using:

screen -r <session-name>

To check for all of the detached sessions you have running, you can use the command:

screen -ls

Once connected to your screen session, you should interrupt the gunicorn process. For example, on Mac, you can usually interrupt a terminal process by pressing cmd + ..

Once your gunicorn process has been interrupted, you can close the screen instance by running:


Killing an orphaned process

If you are not sure whether a gunicorn server is still open on a particular port, you can check using the netstat utility:

netstat -plnt | grep ':90*'

If you see a port listed with a number in the rightmost column (e.g., port 9001 in the screenshot below), that means you still have active processes running on that port.


You end an orphaned process, and free up its port, by using the kill command. Using the example above, we could end the orphaned process by running the command below:

kill -9 87896

where 87896 is the process’ PID number as identified by running the netstat command.

Note: There could be more than one process listening and so you may have to use the kill command multiple times.

For example, if you are trying to close port 9001, you can use the following command to list all the processes that are running on port 9001:

lsof -i:9001

For a more aggressive method to kill all processes listening to a particular port (e.g. port 9001), you can use the following command:

kill -9 $(lsof -t -i:9001)

Copy data off the server

When data collection is complete, the final task is to download the data off the server. You do not need to be on the server in order to do this; instead, you can do it from your local machine.

On Mac, you can copy a datafile (example.json in the code below) as follows:

scp <username>@<server-address>:<path/on/VM/example.json> </local/path/for/file>

You can also copy the entire data directory from the server with the recursive copy option:

scp -r <username>@<server-name><path/on/VM> </local/path/for/folder>