Development

This tutorial describes the procedure to run Open Data Capture on your local system in development mode. For information on how to deploy Open Data Capture in production, please refer to our deployment guide.

System Prerequisites

This setup is designed for Unix-like operating systems and has been tested on MacOS and Linux. We do not support running Open Data Capture on Windows. For Windows users, we recommend using WSL.

Required Packages

MacOS

First, make sure that homebrew is installed on your system. This will also ensure that the Xcode Command Line Tools are available. Then, install the following packages:

brew install bash jq

Ubuntu

Please ensure that the following packages are installed:

apt-get install build-essential jq

Arch Linux

Please ensure that the following packages are installed:

pacman -S base-devel curl git jq

Git Setup

We use Git for version control and host our source code on GitHub. Please fork our repository and clone your fork:

# Replace 'DouglasNeuroinformatics' with your GitHub username
git clone https://github.com/DouglasNeuroInformatics/OpenDataCapture

Next, navigate to the root of the repository:

cd OpenDataCapture

Configuration

All of the required configuration is stored in the file .env, which can be generated from .env.template using the following script:

./scripts/generate-env.sh && source .env

System Dependencies

Now, in order to run the code, we need to install some additional system dependencies (i.e., a JavaScript runtime and database).

Node.js

We use Node Version Manager (nvm) to manage the supported Node version. Please follow the installation instructions to install nvm on your system. Then, install the current Node version with the following command:

nvm install $(cat .nvmrc)

Once installed, enable the pnpm package manager:

corepack enable

Note

This is not the only way to manage Node versions. If you have another preferred method, feel free to use it. However, we strongly recommend against using a system installation of Node.

MongoDB

Now, you need to setup a MongoDB instance. There are several ways you can do this. Please follow the guide for your prefered method:

Docker (Recommended)

First, make sure that Docker and Docker Compose are installed on your system (for installation instructions, please refer to the official documentation). Then, launch the MongoDB container:

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

Once the container is running, we need to create a replication set, as is required by Prisma. This can be done with the following command:

docker compose -f docker-compose.dev.yaml exec mongo mongosh --eval "rs.initiate({_id: 'rs0', members: [{_id: 0, host: 'localhost:27017'}]});"

System Install (MacOS)

Caution

These instructions assume you are using a Mac with Apple Silicon. For older, Intel-based Macs, make sure to adjust the paths as needed (e.g., homebrew is likely installed in /usr/local rather than in /opt/homebrew).

First, install MongoDB using Homebrew:

brew tap mongodb/brew
brew update
brew install mongodb-community@7.0

Then, open /opt/homebrew/etc/mongod.conf and make the following changes:

systemLog:
  destination: file
  path: /opt/homebrew/var/log/mongodb/mongo.log
  logAppend: true
storage:
  dbPath: /opt/homebrew/var/mongodb
net:
  bindIp: 127.0.0.1, ::1
  ipv6: true
replication:
  replSetName: rs0

Next, run MongoDB as a MacOS service:

brew services start mongodb-community@7.0

Finally, initiate the replication set:

mongosh --eval "rs.initiate({_id: 'rs0', members: [{_id: 0, host: 'localhost:27017'}]});"

Runtime Dependencies

Next, install runtime dependencies:

pnpm install

Run Dev Server

Now, you should be able to start the development server, which is configured with hot module replacement.

pnpm dev

Navigate to http://localhost:3000 and you should be greeted with a setup screen. Follow the instructions to create the first admin user and seed the database.