Developer Quickstart

OMOP schema and vocabs setting

You need a pre-seeded OMOP CDM database inside the database of Carrot.

To do this, add a folder named vocabs in the root directory of Carrot, then place there vocabulary files downloaded from Athena.

Thanks to OMOP Lite container, OMOP schema will be created and vocabularies will be loaded to Carrot’s database, when the app’s stack is running.

Authentication setup for Azure functions

For local development, an authentication will be required when api container sends requests to workers container,.

To set this up, at the app/workers directory, add a folder named Secrets. Inside this folder, add a new file named rulestrigger.json with the following content:

{
  "keys": [
    {
      "name": "default",
      "value": "rules_key",
      "encrypted": false
    }
  ]
}

Superuser Credentials setup

A superuser needs to be created to access the Django admin dashboard and Carrot frontend.

To do that, superuser credentials need adding as environment variables by doing the following steps:

• Locate the docker-compose.yml file in the root directory of Carrot.

• Add the following variables to the environment section of the api service:

  environment:
    - SUPERUSER_DEFAULT_USERNAME=<superuser_username>
    - SUPERUSER_DEFAULT_PASSWORD=<superuser_password>
    - SUPERUSER_DEFAULT_EMAIL=<superuser_email> // Defaulted to `user@carrot`
    - ...other variables

• Replace superuser_username, superuser_email, and superuser_password with your desired credentials.

• After the Warm up step is done, a superuser will be created automatically with the credentials you chose above.

Warm up

At the root directory, run to command below to start the application stack using Docker compose.

docker compose up -d

This runs the database (db), Azurite emulator (Azurite), Azure functions (workers) and will build Carrot’s backend (api) and frontend (frontend). This process will be on the background and take some time, but you can always check it through Docker Desktop app.

When all of containers, except omop-lite, are up and running successfully, Carrot’s frontend and backend can be accessed through http://localhost:3000/ and http://localhost:8000/admin/ respectively.

However, please complete the remaining steps, while containers are running, to make sure Carrot is running correctly.

More details about Docker compose’s configuration can be found here.

First instances creation

Create some first instances in Carrot app by logging to Django Admin panel http://localhost:8000/admin/.

1. You can log in to the Admin Panel using the superuser credentials you configured earlier.
2. Once logged in, you will be presented with the Django Admin panel.
3. Following this order, fill out the required information to create new instance of Data Partner, Dataset and Project.

Azure local storage setup

You need to set up an Azurite local storage for local development of Carrot

To do this, with the workers container in Docker Desktop is running, open MS Azure Storage Explorer, and create the following queues (under the tab Storage Accounts - Emulator - Queues) and blob containers (under the tab Storage Accounts - Emulator - Blob Containers).

rules-local
rules-exports-local
uploadreports-local

scan-reports
data-dictionaries
rules-exports

Check-in

You should now be able to access Carrot by logging in at http://localhost:3000/ using your admin credentials created at step 4.

After log in, you will be presented with Projects page.

Try using Carrot by steps in the user quickstart to see if Carrot is running correctly. If you can successfully upload a new scan report, create mapping rules, and finally can export the Mapping rules JSON. That’s a sign that you have successfully install and run Carrot locally.