4.3.5 Deploy
Configure docker-compose files
There are a few environment variables you need to manually set in docker compose files for your installation. The docker compose files for each environment are located in the infrastructure folder:
docker-compose.development-deploy.yml
docker-compose.development-qa.yml
docker-compose.development-staging.yml
docker-compose.development-production.yml
a) Replace any instance of the comma separated available language alpha-2 ISO codes for your localisation needs. These strings tell services how to parse some values. The first item in the comma separated languages string sets the default language. In this example, English is the default language and French language is also available in the application.:
b) Replace any instance of the COUNTRY code. E.G.:
c) Edit the traefik: config appropriately depending on your requirements for HTTPS TLS certification explained in earlier sections. You will see comments in the compose files to help you using our examples.
d) Optional: If you are going to use an SMS or WhatsApp API gateway to deliver beneficiary comms, you will need to amend countryconfig: environment variables and APIs to use the gateway. We have code in the countryconfig service which uses the Infobip SMS gateway environment variables.
Configure permissions in the repository & Deploy (production) workflow
In order to stop the Deploy (production) action from being accidentally run, an approval check has been implemented. When the action runs, a Git issue will open requiring repository administrators to reply approve or deny in order for the action to continue.
In the .github/workflows/deploy-prod.yml change the approvers to a comma separated list of Github usernames for administrators in your repository, and commit the updated workflow to Git:
Your Git repository must be configured to allow Issues and additionally Workflows must have read/write permissions.
Ensure your container has built and pushed to Dockerhub successfully
Before you can deploy, you need to make sure that your country configuration Docker image has compiled and has been pushed to your container registry (E.G. Dockerhub).
Copy the tag associated with your countryconfig Docker container image from the logs of the "Publish image to Dockerhub" Github Action.
In Github, navigate to "Actions" and click "Publish image to Dockerhub" to see the output of the action that automates whenever code merges to "develop", "main", "master" branches. Copy the git commit hash in the Action logs to see how the Docker image was tagged. You will use it in the next step.
Deploy to your server environments
You can deploy to your server using the automated "Deploy (development)" Github Action for development and qa environments and the "Deploy (production)" Github Action for staging and production environments.
First, use Deploy (development) to deploy to a development or qa environment to test the process.
a) You will be required to select the environment that you wish to deploy to.
b) You will be required to enter the OpenCRVS Core Dockerhub image tag for any tagged build on Dockerhub) to refer to the OpenCRVS Core release of choice. Usually this will be an official release: E.G. v1.4.0
c) You will be required to enter the OpenCRVS Country Configuration version (or short Git hash tag for any tagged custom country configuration build on Dockerhub)
d) n Deploy (development), there is a checkbox available to you to "Reset the environment". This will empty all databases in the environment allowing you to re-seed. This is useful during development and testing. In production, there is no way to clear all databases from a Github action as a security posture. You can optionally open an SSH session into the Github Action runner for debugging purposes on the Action itself.
e) Click Run workflow, and watch the output to make sure that the deployment was successful.
Next, you can use the Deploy(production) action to similarly deploy to your production & staging environments.
Seed your environments
Once the environments have been successfully deployed to, they are ready for seeding with your reference data that you prepared locally in step 3.2
Run the Seed data Github Action with the same OpenCRVS Core Dockerhub image tag you used in the Deploy actions to seed the databases with your data.
The Seed data action can only be run once. If an error occurs, the environment must be reset before it can be seeded again.
The Reset environment Github Action can be used to clear an environment of all data. This is useful during testing of development and qa environments where you may have made test registrations.
To protect you from accidentally resetting a production environment, we do not provide an action for this. As part of our Pre-Deployment Checklist, perhaps you have made test registrations on production and are required to clear it before going live. You can amend the .github/workflows/clear-environment.yml file to edit this action's default behaviour by adding production temporarily, in order to reset a production environment. YOU MUST REMOVE THE CAPABILITY TO RESET PRODUCTION after you go live, as you will be capturing real citizen data that could be lost, should a developer accidentally run the action at a later date.
Lock down your servers via networking and distribute VPN client access
Usually you will be using your own VPN and will have received instructions from your network administrator on how to connect to it as an end user. They will have also blocked access to your servers over the public internet.
If you are using the OpenCRVS Wireguard VPN, where in our example the QA environment is acting as the VPN server, we route all traffic via the QA server first:
You will need to make VPN client accounts for all staff.
Browse to https://vpn.<your domain> and use the VPN_ADMIN_PASSWORD secret to login
Add a client for each member of staff, and download the configuration .conf file. The staff member can import that file into the Wireguard Client as a new Tunnel and connect to the VPN.
Our Wireguard VPN is not designed for use at scale. The Wireguard VPN Admin interface hosted at vpn.<your-domain> uses wg-easy. OpenCRVS accepts no responsibility for the penetration testing or security of the Wireguard VPN or WG Easy. Use at your own risk.
Login to OpenCRVS
Now you should be able to browse to OpenCRVS to login.
https://login.<your-domain>
For development & qa environments, your test employees can log straight into your application with 2FA and notifications disabled.
For staging & production environments, your production National System Administrator employee must immediately login and change the password to a strong, minimum 12 character long password.
Then the user will be logged out and will have to login again with 2FA and notifications enabled.
This is your first test of your SMTP service. The National System Administrator should receive an email containing the 2FA code.
Once logged in the National System Administrator can create team members through the user interface.
If there is an issue and you are not receiving emails, this is a good opportunity to learn about monitoring and debugging your OpenCRVS installation.
To monitor and debug OpenCRVS, login to Kibana here:
https://kibana.<your-domain>
The username will be: elastic
The password will be in your .env.<environment> file or moved to 1Password / Bitwarden as encouraged.
Browse to "Observability > Logs".
You can search for logs on any microservice by entering:
As the notification API was configured in the countryconfig service, you can search the appropriate logs like so:
As you browse the logs you are looking for 500 errors and you cna respond to any error messages you see appropriately.
To learn more about OpenCRVS monitoring and maintenance, visit the monitoring section.
Backup & restore
OpenCRVS is automatically configured so that your production environment, backs up to your staging environment every night. Before going live, make a test registration in production and wait 24 hours.
Login to the staging environment after 24 hours, and you should see that the registration exists in the staging environment.
Backups are encrypted and stored in your backup environment every day. Over time you should clear out legacy backups on the backup environment in order to maintain a safe storage capacity on the backup server. You should test that backups are safely restoring on a regular basis.
To learn more about all the technical checks that you should perform before going live with your OpenCRVS installation, re the Pre-deployment Checklist section.
Last updated
