4.2.5.2 Configuring Metabase Dashboards
Last updated
Last updated
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/.
If this is your first time logging into Metabase, you may use the following default credentials:
Username: user@opencrvs.org
Password: m3tabase
We strongly recommend changing these default credentials as your first customisation task!
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.
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.
Next, update the map name and URL environment variables in infrastructure/docker-compose.deploy.yml along with whatever region key you use for the mouse interaction and data disaggregation. Usually the key will always be "State" and the name can be customised to suit your country.:
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.
