Create experiment protocol

Protocol for creating an experiment

Getting started

Option 1: Start a new project

If you are starting a new research project (which is different than starting a new experiment), you can start by cloning exbuilder and specifying a name for your project:

git clone name-of-your-project

This will create a file structure and starting point on your local machine!

Option 2: Create a new experiment in an existing project

If you just need to add an experiment to your existing project, you can do that by creating new experiment in your experiments folder.

Create a new experiment

Add a new folder to experiments

jsPsych study

If you are creating a new jsPsych study, I usually make a copy of the experiment1-jspych folder that comes with exbuilder (or another experiment from that project), or simply edit that folder as my starting point.

lookit study

If you are creating a new lookit study, you can create a folder and include the protocol_generator.js file. It's also good to include a folder of the stimuli you used.

Tip: In general, it's good to make each experiment fairly stand-alone. That means to include things like the jsPsych folder, a stimuli folder, etc. within each experiment.

Edit your config-exbuilder.json file

Push your changes to the lab GitHub

For new projects

Create a new repository

From the lab's GitHub page:, select the green New button. Fill in the Repository name and a Description if you wish. Then select Private (all lab projects begin as private repositories). Then select Create repository.

Creating a new repository on GitHub

Tip: We'll be importing an existing repository, so don't initialize the repository with anything.

Another tip: Ask Katie to create a repository for your project in the lab's GitHub if you do not have that permission level.

Set the new repo as your project's origin

From your local computer, from inside your projects directory

cd yourproject

Set your project's origin to this new GitHub repository so you can push your changes to it.

git remote set-url origin

Then, whenever you make changes to your project on your local computer, you can push them to this repository with

git add .
git commit -m "inital commit"
git push origin main

For existing projects

Step 1: Push your changes to the repository

Whenever you make changes to your project on your local computer, you can push them to your remote repository in the pennchildlanglab GitHub with the following.

cd yourproject
git add .
git commit -m "inital commit"
git push origin main

If you are new to git and repository managers like GitHub, we recommend this nice tutorial by Karl Broman. If you make mistakes, don't worry, we all do. We recommend Oh, Shit! Git!?! to get you through it. Or, Dangit, Git !?! for the "same content without the swears".

Step 2: Pull your changes to the server

Once you've updated your changes locally and pushed them to the repository, you can pull the changes in to the server so that they get reflect there.

cd experiments/yourproject
sudo git pull

Deploy your project on the server

You need to be added as an authorized user on the server to accomplish this! Ask Katie if you need access.

Step 1: ssh into the server

To ssh into the server, from the terminal, run (changing username to your username)

Step 2: add your project

Next, you'll add your project to the experiments directory on the server.

cd experiments

Check to make sure your project is does not already exist on the server by listing the contents of the experiments directory.


If it doesn't already exist, clone your project's GitHub repository with

sudo git clone

Tip: When you create or modify files on the server, you'll need to use the sudo command. You'll be asked to enter your [sudo] password . If you can't remember yours, Katie can reset it for you.

If it does already exist, also check if you have the .env file already created. If yes,

Step 3: configure your .env file

Next you'll need to configure your .env file for the server's environment. From inside your project directory

cd yourproject

Make a copy of the sample environment file inside your repository on the server.

sudo cp .env.sample .env

Then edit the variables with nano

sudo nano .env

You'll need to edit the DB and S3 variables to reflect the lab's database and S3 bucket. These settings are available to lab members in the lab's basecamp.

Step 4: deploy the containers

sudo docker-compose -f docker-compose.deploy.yml up -d --build

Step 5: create a proxy host

Each experiment runs inside its own docker container on the lab's server. To allow participants to visit the container, go to to add a proxy host. Click Add proxy host

Add your a proxy host

You need to enter a unique subdomain of the domain name. We usually use your lastname followed by a number. Then, you'll select the name of your studies nginx container as the forward hostname. You can find out the name by running

sudo docker ps

The only rules are that the subdomain is unique and that you do not give away hints about the study, since participants will visit the URL.

Next you'll want to add an SSL certificate to your proxy host. Before you hit save, click the SSL tab and fill everything in as below.

Request your SSL cert