Getting Started#

Introduction#

Before proceeding, we recommend watching this short introduction video to understand what e-Babylab offers and decide whether it fits your needs.

Prerequisites#

e-Babylab runs in a containerised environment using Docker and Docker Compose, which are both included in Docker Desktop.

Try It Locally#

Run a local instance of e-Babylab for testing or development.

  1. Clone the e-Babylab repository:

    git clone https://github.com/lochhh/e-Babylab.git
cd e-Babylab

    If you plan to make custom changes to the code, fork the repository first, then clone your fork:

    git clone https://github.com/YOUR_GITHUB_USERNAME/e-Babylab.git
cd e-Babylab

  2. Configure your .env file as described in Set Up Environment Variables.

  3. Start e-Babylab in development mode:

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

  4. Set up the database:

    docker compose -f docker-compose.dev.yml exec web uv run python manage.py migrate

  5. Create an admin account for logging into the admin interface:

    docker compose -f docker-compose.dev.yml exec web uv run python manage.py createsuperuser

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

To stop e-Babylab:

docker compose -f docker-compose.dev.yml down

For more information on running tests, managing dependencies, and other development workflows, see the Development guide.

Production Deployment#

Deploy e-Babylab to a production server.

  1. Create the e-Babylab directory and download the required files:

    mkdir e-Babylab && cd e-Babylab
curl -LO https://raw.githubusercontent.com/lochhh/e-Babylab/main/docker-compose.yml
curl -LO https://raw.githubusercontent.com/lochhh/e-Babylab/main/.env.template
curl -LO https://raw.githubusercontent.com/lochhh/e-Babylab/main/nginx.conf.template

  2. Configure your .env file as described in Set Up Environment Variables, then uncomment and set the following production values:

    • Domain and TLS certificates — you will need a domain name pointing to your server and a TLS certificate. Obtain these from your institution’s IT department or a provider such as Let’s Encrypt. Then set DOMAIN, SSL_CERT_PATH, and SSL_KEY_PATH:

      DOMAIN=your-domain.com
SSL_CERT_PATH=/etc/ssl/certs/your_cert.pem
SSL_KEY_PATH=/etc/ssl/private/your_key.key

    • PostgreSQL data directory — POSTGRES_DATA_PATH defaults to ./postgres_data. Change it to an SSD-backed path for better I/O performance if available.

    • e-Babylab version (optional) — IMAGE_TAG defaults to latest. Set it to a specific release version (e.g. 2.0.0) to pin the deployment.

    • Database password — set a strong DB_PASSWORD.

    • Admin account (optional) — set DJANGO_SUPERUSER_USERNAME, DJANGO_SUPERUSER_EMAIL, and DJANGO_SUPERUSER_PASSWORD to auto-create an admin account on first startup. If you skip this, you can create one manually later:

      docker compose exec web python manage.py createsuperuser

  3. Start e-Babylab:

    docker compose up -d

e-Babylab will be available at https://your-domain.com/admin/.

Updating#

A GitHub Actions workflow builds and pushes a new Docker image on every push to main and on version releases. The image tag is configurable via IMAGE_TAG in .env (defaults to latest).

Note

Releases before v2.0.0 are not compatible with this deployment method.

To update to a specific release (e.g. v2.0.0):

cd /path/to/e-Babylab

# Download config files matching the release
curl -Lo docker-compose.yml.new \
  https://raw.githubusercontent.com/lochhh/e-Babylab/v2.0.0/docker-compose.yml
curl -Lo nginx.conf.template.new \
  https://raw.githubusercontent.com/lochhh/e-Babylab/v2.0.0/nginx.conf.template
curl -Lo .env.template.new \
  https://raw.githubusercontent.com/lochhh/e-Babylab/v2.0.0/.env.template

# Review changes before applying
diff docker-compose.yml docker-compose.yml.new
diff nginx.conf.template nginx.conf.template.new
diff .env .env.template.new
# Add any new variables from .env.template.new to your .env
mv docker-compose.yml.new docker-compose.yml
mv nginx.conf.template.new nginx.conf.template
rm .env.template.new

# Set the image tag in .env
IMAGE_TAG=2.0.0

# Pull and restart
docker compose pull
docker compose up -d
docker compose exec web python manage.py migrate

Database Access#

For production database access, use any Postgres client (e.g. psql, pgAdmin, DBeaver) with SSH tunnelling to port 5432 on your server:

ssh -L 5432:localhost:5432 user@your-server

Then connect to localhost:5432 with the credentials from your .env file. pgAdmin is included in the development environment only.

Set Up Environment Variables#

  1. Create your .env file by copying the template:

    cp .env.template .env

  2. Generate a Django SECRET_KEY:

    python -c 'import secrets; print(secrets.token_urlsafe())'

    Or use an online generator such as Djecrety.

    Note

    If your secret key contains special characters like $, \, or `, Docker will try to interpret them as variable references in the .env file. Either wrap the value in single quotes (e.g., SECRET_KEY='my$ecretKey') or regenerate until you get a key without those characters. The secrets.token_urlsafe() method above only produces URL-safe characters and avoids this problem.

  3. Copy the generated key and paste it into the SECRET_KEY field in your .env file.

  4. Configure a CAPTCHA provider (see CAPTCHA Configuration below).

  5. The database connection values (DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT) are pre-filled with defaults that work for local development. If you are deploying to production, make sure to set a strong DB_PASSWORD.

CAPTCHA Configuration#

CAPTCHA protects the participant form from automated submissions that can pollute your study data. We strongly recommend keeping CAPTCHA enabled in production. Disabling it (CAPTCHA_PROVIDER=none) is suitable for development and testing only and leaves your study vulnerable to bot traffic.

Set CAPTCHA_PROVIDER in your .env file to one of the following.

ALTCHA (default)

Turnstile

TrustSig

None

Compliance

Universal (self-hosted, no data leaves your server)

US-based

EU-based (Germany)

N/A

User friction

Invisible (proof-of-work)

Mostly invisible (occasional checkbox if flagged)

Invisible (hardware signals)

N/A

Third-party data

None

Cloudflare (US)

TrustSig (EU)

N/A

Cookies

None

Yes

None

N/A

Cost

Free

Free tier available

Free tier available

N/A

Best for

Privacy-first deployments

Zero server maintenance, easy setup

EU institutions wanting invisible protection

Dev/testing only

CAPTCHA is enabled by setting CAPTCHA_PROVIDER and adding provider‑specific keys in your .env file. The tabs below outline the setup steps for each provider, where to obtain or generate keys, and how to disable CAPTCHA.

Self-hosted proof-of-work — no third-party requests, no cookies, universally compliant with GDPR, CCPA, LGPD, and PIPL. No account needed.

# .env file
CAPTCHA_PROVIDER=altcha

Works out of the box — the HMAC key defaults to one derived from SECRET_KEY. To rotate it independently, set ALTCHA_HMAC_KEY explicitly:

ALTCHA_HMAC_KEY=<generate with: openssl rand -hex 32>

Cloudflare’s checkbox-style CAPTCHA. Easy setup, zero server maintenance.

Register at the Cloudflare Turnstile dashboard, click Add widget, enter your domain, and copy the Site Key and Secret Key. For local development, use Cloudflare’s test keys.

# .env file
CAPTCHA_PROVIDER=turnstile
CLOUDFLARE_TURNSTILE_SITE_KEY=<your site key>
CLOUDFLARE_TURNSTILE_SECRET_KEY=<your secret key>

Invisible hardware-signal bot protection, hosted in Germany (EU). Zero cookies, GDPR compliant.

Register at trustsig.eu, create a new project on the dashboard, and add your production domain to the Allowed Domains list (for local development, no extra setup is needed — localhost and private-network origins are auto-allowed). Then copy the Site Key and Secret Key.

# .env file
CAPTCHA_PROVIDER=trustsig
TRUSTSIG_SITE_KEY=<your pk_live_ key>
TRUSTSIG_SECRET_KEY=<your sk_live_ key>

Disable CAPTCHA entirely. Only use for development/testing.

# .env file
CAPTCHA_PROVIDER=none