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.
After running the command, the dashboards can be accessed using the URL http://localhost:4444/.
Note that for the following steps to work, you must also have the OpenCRVS development environment running on your machine.
In local development environments, you can use the following credentials to log into metabase:
Username: user@opencrvs.org
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.
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
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.
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.
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.
SSH into the manager node of your server fleet
Run docker service scale opencrvs_dashboards=0 to stop the dashboards service
sudo rm /data/metabase/*
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.
