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 production.

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.

To see the dashboards running locally in your client, you can see the URLs that the client will use in the countryconfig repo client-config.js. Copy the URLs and paste them into the empty string placeholders:

window.config = {
  API_GATEWAY_URL: 'http://localhost:7070/',
  CONFIG_API_URL: 'http://localhost:2021',
  LOGIN_URL: 'http://localhost:3020',
  AUTH_URL: 'http://localhost:7070/auth/',
  MINIO_BUCKET: 'ocrvs',
  MINIO_URL: 'http://localhost:3535/ocrvs/',
  COUNTRY_CONFIG_URL: 'http://localhost:3040',
  // Country code in uppercase ALPHA-3 format
  COUNTRY: 'FAR',
  LANGUAGES: 'en,fr',
  SENTRY: '',
  // Use the values in comments when Metabase is running locally
  // http://localhost:4444/public/dashboard/acae0527-74be-4804-a3ee-f8b3c9c8784c#bordered=false&titled=false&refresh=300
  LEADERBOARDS_DASHBOARD_URL:
    'http://localhost:4444/public/dashboard/acae0527-74be-4804-a3ee-f8b3c9c8784c#bordered=false&titled=false&refresh=300',
  // http://localhost:4444/public/dashboard/fec78656-e4f9-4b51-b540-0fed81dbd821#bordered=false&titled=false&refresh=300
  REGISTRATIONS_DASHBOARD_URL:
    'http://localhost:4444/public/dashboard/fec78656-e4f9-4b51-b540-0fed81dbd821#bordered=false&titled=false&refresh=300',
  // http://localhost:4444/public/dashboard/a17e9bc0-15a2-4bd1-92fa-ab0f346227ca#bordered=false&titled=false&refresh=300
  STATISTICS_DASHBOARD_URL:
    'http://localhost:4444/public/dashboard/a17e9bc0-15a2-4bd1-92fa-ab0f346227ca#bordered=false&titled=false&refresh=300',
  FEATURES: {}
}

After running the command, the dashboards can be accessed using the URL http://localhost:4444/.

cd packages/dashboards
yarn start

Note that for the following steps to work, you must also have the OpenCRVS development environment running on your machine.

Metabase login page

In local development environments, you can use the following credentials to log into metabase:

• Username: [e-mail]

• Password: m3tabase

Note: You must configure the username and password for the production environment via environment variables otherwise the deployment will fail as they are required.

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/map.geojson.

The simplest method to customise this map is by modifying the GeoJSON file's content. In local development environment, you should see the map changing right away in Metabase. To verify this, proceed to the Admin Settings by clicking the cog-icon at the top right corner of Metabase, and then navigate to "Maps". In "Custom maps", click on the map labeled "Full country".

If you are not seeing your updates, click on "Refresh" and try directly navigating to the default address http://localhost:3040/content/map.geojson which should now serve the updated GeoJSON.

Notice that changing the map name or url will have no effect after you stop and restart the Metabase environment once. For these to be changed, the Metabase development environment needs to be started using the following environment variables

export OPENCRVS_METABASE_MAP_URL=http://localhost:3040/content/map.geojson
export OPENCRVS_METABASE_MAP_NAME="Full country"
yarn start

Without the variables, these values will always change back to the default ones.

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.