4.2.5.2 Configuring Metabase Dashboards

OpenCRVS includes a self-hosted, pre-configured Dashboards service, built on Metabase. In deployed environments, these dashboards can be found in the metabase.<your domain> address.

The recommended way of customising OpenCRVS dashboards is in a local development environment, during the development phase of the project. It is also possible to customise the dashboards through the Metabase UI once the environment has been deployed but to keep environments consistent and all configuration in version control, we do not recommend this. All changes to production OpenCRVS environments should always be implemented by a developer, committed to version control, thoroughly tested, and only then deployed.

To begin customising the dashboards, first initiate your local dashboards instance by navigating to packages/dashboards and executing yarn start. In development environments, the dashboard service is not automatically started because it consumes significant memory and is not essential for most local development tasks. After running the command, the dashboards can be accessed using the URL http://localhost:4444/.

cd packages/dashboards
yarn start

Metabase login page

If this is your first time logging into Metabase, you may use the following default credentials:

• Username: [e-mail]

• Password: m3tabase

We strongly recommend changing these default credentials as your first customisation task!

Updating the map used in geographical visualisations

Several dashboard visualisations rely on regional maps. The country configuration starter project (opencrvs-countryconfig) provides an example map located at src/api/dashboards/file/farajaland-map.geojson.

The simplest method to customise this map is by modifying the GeoJSON file's content. The map should automatically update upon your next deployment. Should you wish to rename the file or alter the API path from which it is served, proceed to the Admin Settings by clicking the cog-icon at the top right corner of Metabase, and then navigate to "Maps". In this section, you can set up the source for the map visualisation that Metabase utilises.

More information about customising dashboards and creating visualisations can be found from the Metabase documentation.

After customising the dashboards to suit your country's requirements, return to the terminal window where yarn start was executed. Press Ctrl + C to indicate that you are ready to save the configuration changes you've made. Following this action, you should observe a modification in the file dashboards/metabase.init.db.sql.

❯ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   dashboards/metabase.init.db.sql

no changes added to commit (use "git add" and/or "git commit -a")

This file should then be placed in the path infrastructure/metabase/metabase.init.db.sql within your country configuration repository. It is important not to commit these file changes to opencrvs-core! You should see your updated dashboards after you deploy the changed file.

Dashboards not updating after deployment

Note that the file we just generated is only for initialising an empty Metabase instance. If your environment already had OpenCRVS running before your deployment, Metabase has been initialised with the previous init file. To re-initialise your dashboards, please follow the next steps.

Before you do this, make sure there are no configurations that were done manually through the Metabase UI. These changes will be overwritten with your new init file and all changes to Metabase will be lost permanently.

1. SSH into the manager node of your server fleet

2. Run docker service scale opencrvs_dashboards=0 to stop the dashboards service

3. sudo rm /data/metabase/*

4. Run docker service scale opencrvs_dashboards=1 to start the dashboards again

After this you should see your changes just as they are in version control.