Skip to content

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

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:

Terminal window
brew install bash jq

Git Setup

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

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

Next, navigate to the root of the repository:

Terminal window
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:

Terminal window
./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:

Terminal window
nvm install $(cat .nvmrc)

Once installed, enable the pnpm package manager:

Terminal window
corepack enable

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:

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:

Terminal window
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:

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

Runtime Dependencies

Next, install runtime dependencies:

Terminal window
pnpm install

Setup Database

Now, we need to generate the database schemas:

Terminal window
pnpm ws database db:generate && pnpm ws database db:push

Run Dev Server

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

Terminal window
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.