OpenCRVS
v1.5
v1.5
  • 👋Welcome!
  • CRVS Systems
    • Understanding CRVS
    • Effective digital CRVS systems
    • OpenCRVS within a government systems architecture
    • OpenCRVS Value Proposition
  • Product Specifications
    • Functional Architecture
    • Workflow management
    • Status Flow Diagram
    • Users
      • Examples
    • Core functions
      • 1. Notify event
      • 2. Declare event
      • 3. Validate event
      • 4. Register event
      • 5. Print certificate
      • 6. Issue certificate
      • 7. Search for a record
      • 8. View record
      • 9. Correct record
      • 10. Verify record
      • 11. Archive record
      • 12. Vital statistics export
    • Support functions
      • 13. Login
      • 14. Audit
      • 15. Deduplication
      • 16. Performance management
      • 17. Payment
      • 18. Learning
      • 19. User support
      • 20. User onboarding
    • Admin functions
      • 21. User management
      • 22. Comms management
      • 23. Content management
      • 24. Config management
    • Data functions
      • 25. Legacy data import
      • 26. Legacy paper import
  • Technology
    • Architecture
      • Performance tests
    • Standards
      • FHIR Documents
        • Event Composition
        • Person
        • Registration Task
        • Event Observations
        • Locations
    • Security
    • Interoperability
      • Create a client
      • Authenticate a client
      • Event Notification clients
      • Record Search clients
      • Webhook clients
      • National ID client
      • FHIR Location REST API
      • Other ways to interoperate
  • Default configuration
    • Intro to Farajaland
    • Civil registration in Farajaland
    • OpenCRVS configuration in Farajaland
      • Application settings
      • User / role mapping
      • Declaration forms
      • Certificate templates
    • Business process flows in Farajaland
  • Setup
    • 1. Planning an OpenCRVS Implementation
    • 2. Establish project and team
    • 3. Gather requirements
      • 3.1 Mapping business processes
      • 3.2 Mapping offices and user types
      • 3.3 Define your application settings
      • 3.4 Designing event declaration forms
      • 3.5 Designing a certificate template
    • 4. Installation
      • 4.1 Set-up a local development environment
        • 4.1.1 Install the required dependencies
        • 4.1.2 Install OpenCRVS locally
        • 4.1.3 Starting and stopping OpenCRVS
        • 4.1.4 Log in to OpenCRVS locally
        • 4.1.5 Tooling
          • 4.1.5.1 WSL Support
      • 4.2 Set-up your own, local, country configuration
        • 4.2.1 Fork your own country configuration repository
        • 4.2.2 Set up administrative address divisions
          • 4.2.2.1 Prepare source file for administrative structure
          • 4.2.2.2 Prepare source file for statistics
        • 4.2.3 Set up CR offices and Health facilities
          • 4.2.3.1 Prepare source file for CRVS Office facilities
          • 4.2.3.2 Prepare source file for health facilities
        • 4.2.4 Set up employees & roles for testing or production
          • 4.2.3.1 Prepare source file for employees
          • 4.2.3.2 Configure role titles
        • 4.2.5 Set up application settings
          • 4.2.5.1 Managing language content
            • 4.2.5.1.1 Informant and staff notifications
          • 4.2.5.2 Configuring Metabase Dashboards
        • 4.2.6 Configure certificate templates
        • 4.2.7 Configure declaration forms
          • 4.2.7.1 Configuring an event form
        • 4.2.8 Seeding & clearing your local databases
        • 4.2.9 Countryconfig API endpoints explained
      • 4.3 Set-up a server-hosted environment
        • 4.3.1 Verify servers & create a "provision" user
        • 4.3.2 TLS / SSL & DNS
          • 4.3.2.1 LetsEncrypt https challenge in development environments
          • 4.3.2.2 LetsEncrypt DNS challenge in production
          • 4.3.2.3 Static TLS certificates
        • 4.3.3 Configure inventory files
        • 4.3.4 Create a Github environment
          • 4.3.4.1 Environment secrets and variables explained
          • 4.3.4.2 VPN Recipes
        • 4.3.5 Provisioning servers
          • 4.3.5.1 SSH access
          • 4.3.5.2 Building, pushing & releasing your countryconfig code
          • 4.3.5.3 Ansible tasks when provisioning
        • 4.3.6 Deploy
          • 4.3.6.1 Running a deployment
          • 4.3.6.2 Seeding a server environment
          • 4.3.6.3 Login to an OpenCRVS server
          • 4.3.6.5 Resetting a server environment
        • 4.3.7 Backup & Restore
          • 4.3.7.1 Restoring a backup
          • 4.3.7.2 Off-boarding from OpenCRVS
    • 5. Functional configuration
      • 5.1 Configure application settings
      • 5.2 Configure registration periods and fees
      • 5.3 Managing system users
    • 6. Quality assurance testing
    • 7. Go-live
      • 7.1 Pre-Deployment Checklist
    • 8. Operational Support
    • 9. Monitoring
      • 9.1 Application logs
      • 9.2 Infrastructure health
      • 9.3 Routine monitoring checklist
      • 9.4 Setting up alerts
      • 9.5 Managing a Docker Swarm
  • General
    • Community
    • Contributing
    • Releases
      • v1.5.1: Release notes
      • v1.5.0: Release notes
      • v1.4.1: Release notes
      • v1.4.0 to v1.4.1 Migration notes
      • v1.4.0 Release notes
      • v1.3.* to v1.4.* Migration notes
      • v1.3.5: Release notes
      • v1.3.4: Release notes
      • v1.3.3: Release notes
      • v1.3.1: Release notes
      • v1.3.0: Release notes
      • v1.2.1: Release notes
      • Patch: Elasticsearch 7.10.2
      • v1.2.0: Release notes
      • v.1.1.2: Release notes
      • v.1.1.1: Release notes
      • v1.1.0: Release notes
    • Roadmap
Powered by GitBook
On this page
  1. Setup
  2. 4. Installation
  3. 4.2 Set-up your own, local, country configuration
  4. 4.2.5 Set up application settings

4.2.5.2 Configuring Metabase Dashboards

Previous4.2.5.1.1 Informant and staff notificationsNext4.2.6 Configure certificate templates

Last updated 8 months ago

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

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.

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

  • Username: user@opencrvs.org

  • Password: m3tabase

Updating the map used in geographical visualisations

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

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.

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.

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

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

If you are not seeing your updates, click on "Refresh" and try directly navigating to the default address which should now serve the updated GeoJSON.

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

environment variables
opencrvs-countryconfig
http://localhost:3040/content/map.geojson
the Metabase documentation
Metabase login page