Skip to content

Latest commit

 

History

History
140 lines (98 loc) · 9.77 KB

README.md

File metadata and controls

140 lines (98 loc) · 9.77 KB
Raw

e-Babylab

e-Babylab (Lo et al., 2023) is an open source authoring tool that allows users or researchers to easily create, host, run, and manage online experiments, without writing a single line of code. Using this tool, experiments can be programmed to include any combinations of image, audio, and/or video contents as stimuli and record key presses, clicks, screen touches, audio, video, and eye gaze1. Short-form versions of the MacArthur–Bates Communicative Development Inventories (CDIs; Chai et al., 2020; Mayor & Mani, 2019) can additionally be included in experiments, allowing users or researchers to collect CDI data online.

Contents

  1. Installation
  2. Executing Django Commands
  3. Upgrade
  4. Troubleshooting
  5. Useful Links

1. Installation

Requirements

e-Babylab runs in a containerized environment using Docker and Docker Compose. No other software is required.

To install Docker, please follow the instructions below:

For development, we recommend you to study the Docker and Docker Compose documentation.

Define User-Specific Variables

To set up e-Babylab, there are 3 variables (i.e., the Django SECRET KEY, the reCAPTCHA SITE KEY, and the reCAPTCHA SECRET KEY) specific to your own instance of e-Babylab, which you will have to define in a .env file:

  1. Create your .env file by copying .env.template. Make sure that this file is in the same directory as .env.template.
  2. Create your own Django SECRET KEY using python -c 'import secrets; print(secrets.token_urlsafe())' or use Djecrety.
  3. Go to Google reCAPTCHA and click on "v3 Admin Console". Sign in with a Google account and fill out the site registration form.
  4. Provide a label (e.g., e-Babylab).
  5. Select reCAPTCHA v3 as reCAPTCHA type.
  6. If you are running e-Babylab in a local development environment, add localhost to Domains, otherwise (i.e., running in production) add your own domain, e.g., your_domain.com. You can update and add new domains as needed later on.
  7. When you are done, click on "Submit" and you will have your site key and secret key.
  8. Copy the site key to GOOGLE_RECAPTCHA_SITE_KEY and the secret key to GOOGLE_RECAPTCHA_SECRET_KEY in your .env file.

Run Local Development Environment

For local development, you can run a development version of e-Babylab using the following command:

docker-compose -f docker-compose.dev.yml up -d

The development environment additionally installs pgadmin for easy access to the database. It will be accessible via a random port on your system. You can use docker ps -a to find out about the port. pgadmin is then at http://localhost:PORT/login. You can find the credentials for pgadmin in the docker-compose.dev.yml file.

If you are running e-Babylab for the first time, you will need to:

  1. Set up the database using docker-compose -f docker-compose.dev.yml exec web python manage.py migrate.
  2. Expose new static files (e.g., JavaScript files) using docker-compose -f docker-compose.dev.yml exec web python manage.py collectstatic.
  3. Create a superuser (for logging into the admin interface) using docker-compose -f docker-compose.dev.yml exec web python manage.py createsuperuser.

Once everything is set up, e-Babylab can be accessed at http://localhost:8080/admin/.

If you have made any changes to the data models during development, you will need to create migration files and apply these afterwards. Migration files can be created using docker-compose -f docker-compose.dev.yml exec web python manage.py makemigrations and applied using docker-compose -f docker-compose.dev.yml exec web python manage.py migrate. For more information about migrations, please refer to the Django documentation.

e-Babylab can be stopped using Ctrl + C or docker-compose -f docker-compose.dev.yml down. To stop e-Babylab without destroying the containers, use docker-compose -f docker-compose.dev.yml stop. For more information about their differences, please refer to the documentation for docker-compose down and docker-compose stop.

Run in Production

The production environment of e-Babylab additionally uses nginx for HTTPS/TLS support. You will need to:

  1. Create docker-compose.yml by copying docker-compose.yml.template and add valid TLS certificates to the nginx container via volumes in docker-compose.yml.
  2. Create nginx.conf by copying nginx.conf.template and replace <your_domain.com> with your actual domain.

By default, the TLS certificates are expected to be at the following locations:

  • /etc/ssl/certs/cert.pem
  • /etc/ssl/private/server.key

The locations can be customized in the nginx config nginx.conf.

Use the following command to start:

docker-compose up -d

After starting, Django admin will be available at https://<your_domain.com>:8443/admin.

As mentioned before, if you are running e-Babylab for the first time, you will need to:

  1. Set up the database using docker-compose exec web python manage.py migrate.
  2. Expose new static files (e.g., JavaScript files) using docker-compose exec web python manage.py collectstatic.
  3. Create a superuser (for logging into the admin interface) using docker-compose exec web python manage.py createsuperuser.

2. Executing Django Commands

You can use the following commands to execute commands inside the Django container:

docker-compose exec web django-admin <command> [options]
docker-compose exec web python manage.py <command> [options]

These can be used, for example, to perform upgrades or to create superusers. All available commands can be found here.

3. Upgrade

To upgrade an existing environment to the latest version of e-Babylab, please run the following steps:

  1. We recommend installing e-Babylab from either a public or private git repository, to persist your settings. To pull the latest changes from the repository, please run git pull.

  2. To upgrade, we first need to recreate all containers, so that they are using the latest version of e-Babylab.

    First shutdown the environment using docker-compose down. This will remove all containers, but retain the volumes which contain all of your data.

    Next run docker-compose build to force a rebuild of the e-Babylab container.

    Finally you can restart the environment using docker-compose up -d.

  3. Next you need to perform the database migration. You can apply all migrations using docker-compose exec web python manage.py migrate.

  4. To expose new static files (e.g., JavaScript files), run docker-compose exec web python manage.py collectstatic.

4. Troubleshooting

Web Container starts with "exec: \"./wait-for-it.sh\": permission denied"

Allow the execution of the wait-for-it.sh script by executing the following command: chmod +x ipl/wait-for-it.sh

"Server error (500)" when attempting to download results

Make sure that there is a "webcam" directory in the "ipl" directory (where manage.py and the Dockerfile are located). If it does not exist, create one.

"Can't find a suitable configuration file in this directory or any parent. Are you in the right directory?"

Docker is unable to locate docker-compose.yml. Either create this file (by copying docker-compose.yml.template) or run docker-compose commands with -f docker-compose.dev.yml (e.g., docker-compose -f docker-compose.dev.yml build).

"invalid reCAPTCHA" at Demographic Data page

From 15.05.2021 onwards, reCAPTCHA verification is required in the Demographic Data (i.e., Participant Form) page. Experiments created before 15.05.2021 do not have reCAPTCHA in the Demographic Data page template. To add this, you will need to copy and paste the HTML code of the Demographic Data page template of a new experiment:

  1. Create a new experiment.
  2. Navigate to the Demographic Data page template.
  3. Open the source code view (accessed via the "<>" icon on the toolbar).
  4. Copy the HTML code and paste this to the Demographic Data page template of your experiment and modify the text accordingly.

5. Useful Links

This software is licensed under the Apache 2 License.

Footnotes

  1. Online webcam eye-tracking is currently under beta testing. This feature is implemented based on WebGazer (Papoutsaki et al., 2016) and allows self-calibration using participants' gaze to better suit e-Babylab's use with young children. ↩