Skip to content

Set up a local development environment

The following instructions will guide you through the process of setting up Opal locally on your machine. This guide is split into several aspects of the Opal solution because some components are less frequently worked on.

Required software

In general, all projects with the exception of one project (the mobile app) are containerized. Therefore, the required software to be installed on your machine directly is fairly small.

Note about node

We strongly recommend installing node via the Node Version Manager (nvm) (nvm for macOS, nvm for Windows). It makes it possible to install different node versions, quickly switch between different versions, and makes updating Node painless.

Supported operating systems

As our team uses macOS (Apple Silicon) and Windows machines, we strive to support both these operating systems for local development.

Set up main components

The components most frequently being worked on are the user and clinical staff facing ones. Therefore, the following instructions focus on these components. The other components are considered optional.

Clone repositories using the GitHub CLI

Instead of cloning repositories "manually" by copying their git URL from the project page and cloning it via git clone it is also possible to use the GitHub CLI to do so.

The CLI provides the repo clone command to clone repositories.

Set up your own Firebase project

The user applications communicate via Firebase with the Opal PIE. You need your own Firebase project so that your local app can communicate with the backend components.

Follow the instructions on how to set up a Firebase project.

Note that the instructions on restricting permissions are optional for development.

Set up the legacy databases

All legacy databases are managed using Alembic. Follow the instructions in the db-management README to set them up.

Ensure that you also insert the test data via the reset_data.sh script as outlined in the instructions.

Set up OpalAdmin

Follow the OpalAdmin README to set it up.

In addition, there are management commands that initialize required data as well as test data.

Run the following management commands:

python manage.py initialize_data
python manage.py insert_test_data OMI

See the command's help to learn about all options.

The initialize_data command generates authentication tokens for system users that are needed for configuring other components via their environment files.

Then, migrate all legacy OpalAdmin users to the new OpalAdmin.

python manage.py migrate_users

Then, set the password of the user admin to a password of your choice.

python manage.py changepassword admin

Set up the listener

Follow the instructions outlined in the listener README to set it up.

Once the listener is running, initialize the test users in Firebase with the initialize_users script:

curl --silent --show-error --fail --location https://raw.githubusercontent.com/opalmedapps/opal-admin/main/opal/core/management/commands/files/initialize_firebase_users.js | docker compose exec --no-TTY app node

The script creates several test users all with the same password (see the script). You can also pass --delete-all-users to the script to delete all users (not just the users listed in the script) in the Firebase project.

Set up legacy OpalAdmin

Follow the instructions outlined in the Legacy OpalAdmin README to set it up.

Once it is running you can log in with the user admin and the password you set above when setting up OpalAdmin.

Set up the mobile app

Follow the instructions outlined in the mobile app README.

Optional: User Registration

Setting up the above components will give you the ability to use the mobile app and manage clinical data (such as questionnaires, appointment descriptions etc.) with opalAdmin.

If you need to create new user accounts you can set up the user registration as well. Follow the instructions in the registration README.

Other components

Setting up the above components will give you the ability to use the mobile app, manage clinical data, and register new caregivers so that they can access a patient's data.

All other components as outlined in the component overview are only necessary if you want to contribute to that component specifically. Follow the README in any project to set it up, and update the respective environment variables in other components that make API calls to it.

  1. You are welcome to use another container engine. However, all the commands shown in our instructions are specific to docker and docker compose. ↩