Setting Up a Local PDK Server
In Stage 1 you used rex-local-download, which stores data inside the extension itself and lets you download it as a JSON file. That is useful for exploration, but in a real study you want data flowing automatically to a server as participants browse.
The server component REX is designed to work with is called Passive Data Kit (PDK). This guide walks you through running PDK on your own computer using Docker Desktop, so you can test the complete data pipeline before committing to a production deployment.
Estimated time: 20 minutes.
What is PDK?
Section titled “What is PDK?”Passive Data Kit is an open-source server framework designed for collecting behavioral data from research participants. It stores incoming records, tracks which participants have submitted data, and provides an admin interface for reviewing and exporting collected data.
Running PDK locally means the server lives on your machine. Data goes from the extension to http://localhost:8000 instead of to a remote server. Once you are confident the pipeline works, you can deploy PDK to a real server for a production study; that is covered in Deploy.
Prerequisites
Section titled “Prerequisites”Before starting, you need two things.
Docker Desktop: Docker runs the PDK server in a container, so you do not have to install Python, a database, or any of PDK’s dependencies directly on your machine.
Download and install Docker Desktop from: https://www.docker.com/products/docker-desktop/
After installing, open Docker Desktop and wait until the whale icon in your menu bar (Mac) or system tray (Windows) shows a green status indicator. Docker must be running before any of the commands below will work.
Clone the rex-dev-infrastructure repo onto your computer. This repository contains the Docker configuration for running PDK locally.
git clone https://github.com/bric-digital/rex-dev-infrastructure.git1. Initialize the submodule
Section titled “1. Initialize the submodule”git submodule update --init2. Configure environment
Section titled “2. Configure environment”cp .env.example .envcp containers/passive_data_kit/docker/template.env containers/passive_data_kit/docker/.envStep 1: Start the server
Section titled “Step 1: Start the server”Navigate into the repo and start the containers:
cd rex-dev-infrastructuredocker compose up -dThe -d flag runs the containers in the background (detached mode), so you get your terminal prompt back immediately. The first time you run this, Docker will download the PDK image, which may take a few minutes depending on your connection.
Step 2: Verify it is running
Section titled “Step 2: Verify it is running”Check that the containers started successfully:
docker compose psYou should see one or more containers listed with a status of Up or running. If any show Exit or Restarting, see the troubleshooting section below.
Then open http://localhost:8000/ in your browser. You should see the PDK interface: a login screen or dashboard. If you see a “connection refused” error, the server has not finished starting yet; wait 10–15 seconds and try again.
Step 3: Note the server URL
Section titled “Step 3: Note the server URL”Your local PDK server URL is:
http://localhost:8000You will need this in the next guide when you configure the extension to send data to PDK.
Troubleshooting
Section titled “Troubleshooting”“Port already in use”
Another process on your machine is already using port 8000. Open docker-compose.yml in the rex-dev-infrastructure folder and find the port mapping (it will look like "8000:8000"). Change the left side to a different port, such as "8080:8000". After saving, run docker compose up -d again. Your server URL will then be http://localhost:8080 instead.
“Docker not running” or “Cannot connect to the Docker daemon”
Open Docker Desktop from your Applications folder (Mac) or Start menu (Windows) and wait for it to fully start before running the docker compose command. Docker Desktop needs to be running in the background for any Docker commands to work.
“Permission denied”
On Mac or Linux you may need elevated permissions:
sudo docker compose up -dEnter your system password when prompted.
Containers stop after closing the terminal
If you used docker compose up without -d, the containers are attached to your terminal session and will stop when you close it. Re-run with the -d flag. To stop the containers intentionally at any time, run docker compose down from the rex-dev-infrastructure directory.
Next step
Section titled “Next step”With the server running, the next step is to tell your extension to send data there instead of storing it locally.