OpenCRVS
v1.2
Search…
⌃K

3.3.6 Deploy (Automated & Manual)

Steps required to build your country configuration to a Docker Container Registry and Deploy your OpenCRVS to a server hosted environment.

Automated continuous deployment

The easiest way to deploy OpenCRVS to your servers is to use automated continuous deployment.
Refer to our supplied "Publish image to Dockerhub" Github Action and our supplied "Deploy" Github Action in the country configuration repo to set up appropriate environments for your use case or customise your own delivery pipeline. You could rewrite our Actions for use in Gitlab, Jenkins, Travis, CircleCI or Azure Pipelines for example.
In our example, we have 3 environments provisioned in Github. These environments allow you to provision different subdomains, secrets and optional deployment properties depending on your chosen environment when running the action.
All of our workflows can be manually run from a shell script, so you can deploy from your local machine too if you like. Manual steps are explained below each automated step.
To use our automated Github Action workflow, first you need to ensure that you have set up at least one, or optionally all, of the following Git environments:
a) Staging - A useful environment for testing, where the environment variable NODE_ENV is set to development and you can create test user accounts with a 6 zero "000000" 2FA code during login. This allows us to see a debug experience.
b) QA - A quality assurance/pseudo production environment for software testers, where the environment variable NODE_ENV is set to production and a secondary exception variable QA_ENV is set to true. This allows us to see a production like experience, but with the capability of still creating test user accounts with a 6 zero "000000" 2FA code during login.
c) Production - A live environment, where NODE_ENV is set to production & QA_ENV is set to false and random 2FA is enabled so a comms Gateway must be active as in step 3.3.3.
Our supplied Github Actions are examples that cannot be edited from a fork. You should duplicate these Github Actions files if you want to make changes for your infrastructure and update the branches that dispatch them (here for example) from master, develop to master-<your country alpha3 code>, develop-<your country alpha3 code> as we described in the fork section 3.2.1.

Publishing your country configuration

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).
Option 1: Using our automated action to publish your country configuration
We supply an automated action to do this for you. Our "Publish image to Dockerhub" Github Action is set to automatically run on your country configuration repository whenever code is pushed to a branch named master, main or develop. This action will build and push your Docker image to Dockerhub. You must edit this action if you wish to use a different container registry.
The image will be tagged with the short Git commit hash. This hash is important to refer to and use in the deploy step.
Global repository secrets
These secrets below must be set as global repository secrets in Github as they apply to all environments and are used by the "Publish image to Dockerhub" Github Action
👍
Parameter
Description
DOCKER_USERNAME
Your Dockerhub username to access the container registry. If you are using a different container registry, you will need to manually edit the deploy.yml appropriately.
DOCKER_PASSWORD
Your Dockerhub password.
DOCKERHUB_ACCOUNT
The name of your Dockerhub account or organisation that forms the URL to your country config docker image on Dockerhub before the slash. e.g: opencrvs
DOCKERHUB_REPO
The name of your Dockerhub repository that forms the URL to your country config docker image on Dockerhub after the slash.. e.g. ocrvs-farajaland
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 deploy step.
Option 2: Manually publishing your country configuration
You can navigate to the country configuration repository to build your image from the command line if you wish:
cd opencrvs-farajaland
Export all of the required secrets as environment variables:
export DOCKER_PASSWORD=<your-docker-password> \
export DOCKER_USERNAME=<your-docker-username> \
export DOCKERHUB_ACCOUNT=<your-dockerhub-account> \
export DOCKERHUB_REPO=<your-dockerhub-repo>
Run the following script:
yarn compose:push:version
Take note of the githash at the end of the process to use in the next step ...

Deploying

Next, you need to deploy to your server environments.
Option 1: Using our automated action to deploy
Create the following Github secrets for the usernames and passwords you created earlier when provisioning the servers using Ansible in step 3.3.2, along with other secrets Github will use to SSH into your servers, set the Traefik SSL hostname and connect to your container registry (E.G. Dockerhub) etc.
Note: Using a strong password service such as 1Password you should store the usernames and passwords you create in this section as you will need them regularly.
Global repository secrets
These secrets below must be set as global repository secrets in Github as they apply to all environments and are used by the Github Action:
Secret
Description
ELASTICSEARCH_SUPERUSER_PASSWORD
The Elasticsearch superuser password. You can also use this to login to Kibana with the username "elastic" and you have superuser Elastic privileges. Kibana URL: https://kibana.<your_domain>
KIBANA_USERNAME
A username for a regular Kibana user to login and monitor OpenCRVS stack health. Useful for developers as this user will have no superuser privileges.
KIBANA_PASSWORD
A password for a regular Kibana user to login and monitor OpenCRVS stack health
MONGODB_ADMIN_USER
The MongoDB superuser admin username. A powerful account that has all rights to OpenCRVS data
MONGODB_ADMIN_PASSWORD
The MongoDB superuser admin password.
MINIO_ROOT_USER
A username for a Minio superuser admin to login to the Minio console to view supporting document attachments submitted during registrations. https://minio-console.<your_domain>
MINIO_ROOT_PASSWORD
A password for a Minio superuser admin
DOCKER_USERNAME
Your Dockerhub username to access the container registry. If you are using a different container registry, you will need to manually edit the deploy.yml appropriately.
DOCKER_PASSWORD
Your Dockerhub password.
DOCKERHUB_ACCOUNT
The name of your Dockerhub account or organisation that forms the URL to your country config docker image on Dockerhub before the slash. e.g: opencrvs
DOCKERHUB_REPO
The name of your Dockerhub repository that forms the URL to your country config docker image on Dockerhub after the slash.. e.g. ocrvs-farajaland
SMTP_HOST
Described in step 3.3.4
SMTP_PORT
Described in step 3.3.4
SMTP_USERNAME
Described in step 3.3.4
SMTP_PASSWORD
Described in step 3.3.4
ALERT_EMAIL
Described in step 3.3.4
Environment secrets
The following secrets are likely to be unique for each environment so they should be duplicated as environment secrets in Github and are used by the Github Action:
The Github Action uses this library to SSH into your environments, so needs an SSH Key id_rsa for an SSH Key that has access.
In production, we recommend that SSH key access to servers is managed using a bastion with features for administrators that promote infrastructure security, including key management and auditing. A good OpenSource Bastion is Bastillion.
Parameter
Description
Example
KNOWN_HOSTS
You will need the lines in the .ssh/known_hosts file relevant to the environments that the SSH Key uses. This can be generated using a test SSH connection using your key.
SSH_KEY
This is a copy of the id_rsa file for the SSH Key, not the id_rsa.pub!
STAGING_DOMAIN or QA_DOMAIN or PRODUCTION_DOMAIN
The host domain name (without www!) for your environment. You must make sure that you can ping this domain and that the ping resolves to your manager server's IP address. If this does not resolve, there must be a problem with your A record configuration explained in the previous step 3.3.5.
REPLICAS
The number of replicas: 1, 3 or 5 depending on how many servers are in the environment cluster as explained in step 3.3.1
1
FACTORY_RESET
This is a destructive action. The options can be "yes" or "no". If this is set to yes, then every time the Github Action runs, OpenCRVS data on the server will be cleared and restored to factory default backups explained in step 3.2.6. This is useful for staging or QA environments, for developers and testers. For production automated deployments, or when you are configuring the forms, set to no as you would not want each deployment to factory reset OpenCRVS. This is a process which deletes any registrations or users made and restores reference data explained in step 3.2.6.
no
You can deploy to your server with the following manually triggered action from Github named "Deploy". Navigate to "Actions", and click "Deploy."
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 if you have performed no customisations to core. E.G. v1.2.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) to refer to your country configuration image and githash created by the previous "Publish image to Dockerhub" action. E.G. 4e39a2a
d) Click Run workflow, and watch the output to make sure that the deployment was successful.
Once the deployment is complete, you should be able to navigate to your OpenCRVS URLs.
To login to OpenCRVS: https://login.<your_domain>
To login to OpenHIM: https://openhim.<your_domain>
To login to Kibana: https://kibana.<your_domain>
To login to Minio: https://minio-console.<your_domain>
Option 2: Manual deploy
You can navigate to the Core repository to deploy from the command line if you wish:
cd opencrvs-core
Export all of the required secrets as environment variables:
export DOCKER_PASSWORD=<your-docker-password> \
export DOCKER_USERNAME=<your-docker-username> \
export DOCKERHUB_ACCOUNT=<your-dockerhub-account> \
export DOCKERHUB_REPO=<your-dockerhub-repo> \
export ELASTICSEARCH_ADMIN_USER=elastic \
export ELASTICSEARCH_SUPERUSER_PASSWORD=<your-ELASTICSEARCH_SUPERUSER_PASSWORD> \
export MONGODB_ADMIN_USER=<your-MONGODB_ADMIN_USER> \
export MONGODB_ADMIN_PASSWORD=<your-MONGODB_ADMIN_PASSWORD> \
export MINIO_ROOT_USER=<your-MINIO_ROOT_USER> \
export MINIO_ROOT_PASSWORD=<your-MINIO_ROOT_PASSWORD> \
export KIBANA_USERNAME=<your-KIBANA_USERNAME> \
export KIBANA_PASSWORD=<your-KIBANA_PASSWORD> \
export SMTP_HOST=<your-SMTP_HOST> \
export ALERT_EMAIL=<your-ALERT_EMAIL> \
export SMTP_USERNAME=<your-SMTP_USERNAME> \
export SMTP_PASSWORD=<your-SMTP_PASSWORD> \
export SMTP_PORT=<your-SMTP_PORT> \
Run the following script substituting the parameters as explained in the table below:
bash deploy.sh --clear-data=<FACTORY_RESET> --restore-metadata=<FACTORY_RESET> <ENVIRONMENT> <DOMAIN> <CORE_VERSION> <COUNTRY_CONFIG_VERSION> <PATH_TO_COUNTRY_CONFIG_DIRECTORY> <REPLICAS>
Parameter
Description
Example
FACTORY_RESET
This is a destructive action. The options can be "yes" or "no". If this is set to yes, then when the script runs, OpenCRVS data on the server will be cleared and restored to factory default backups explained in step 3.2.6. This is useful for staging or QA environments, for developers and testers. For production automated deployments, or when you are configuring the forms, set to no as you would not want each deployment to factory reset OpenCRVS. This is a process which deletes any registrations or users made and restores reference data explained in step 3.2.6.
yes
ENVIRONMENT
Can be set to "development", "qa" or "production" with the impact on 2FA and comms delivery as previously explained in step 3.3.3
development
DOMAIN
The host domain name (without www!) for your environment. You must make sure that you can ping this domain and that the ping resolves to your manager server's IP address. If this does not resolve, there must be a problem with your A record configuration explained in the previous step 3.3.5.
CORE_VERSION
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 if you have performed no customisations to core. E.G. v1.2.0
v1.2.0
COUNTRY_CONFIG_VERSION
The OpenCRVS Country Configuration version (or short Git hash tag for any tagged custom country configuration build on Dockerhub) to refer to your country configuration image and githash created by the previous "Publishing your country configuration" step.
4e39a2a
PATH_TO_COUNTRY_CONFIG_DIRECTORY
The local path to your country configuration repository folder.
/home/user/Documents/opencrvs-farajaland
REPLICAS
The number of replicas: 1, 3 or 5 depending on how many servers are in the environment cluster as explained in step 3.3.1
1