3.3.6 Deploy

The best way to deploy OpenCRVS to your stack is by using our supplied Github Actions in the country configuration repo and set up appropriate Git environments for your use case. These environments allow you to provision different subdomains, secrets and optional deployment properties depending on your chosen deployment environment when running the action.
1. 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 developers, 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, SMS random 2FA is enabled so an SMS Gateway must be active.
2. Next, you need to create the following Github secrets for the usernames and passwords you created earlier when provisioning the servers using Ansible, along with other secrets Github will use to SSH into your servers, set the Traefik SSL hostname and connect to Dockerhub etc.
Note: Using a strong password service such as 1Password you should store the passwords you create in this section as you will need them regularly.
These secrets below can be set as global repository secrets in Github as they apply to all environments:
DOCKER_USERNAME - Your Dockerhub username
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 before the slash. e.g: opencrvs
DOCKERHUB_REPO - The name of your Dockerhub repository .. the name of your country config docker image 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 - The email address of your Technical System Administrator who should receive server health alerts. Described in step 3.3.4​
3. The following secrets are likely to be unique for each environment so they should be duplicated as environment secrets in Github
Github needs a deployment SSH key to be enabled. FYI we use this Github action to connect.
KNOWN_HOSTS - You will need a copy of the KNOWN_HOSTS line in .ssh/known_hosts relevant to the host domain name for your environment. This will have been generated using a test SSH connection using your key
SSH_KEY - Note: This is a copy of the id_rsa file for your deploy 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 the setup introduced above.
FACTORY_RESET - This is a destructive action for Staging and QA. For production, set to no as you do 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. For Staging and QA, you can optionally set this to yes and OpenCRVS will reset on each deploy, deleting registrations and restoring all data. A useful option for developers and testers.
4. With these secrets the first "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. The image will be tagged with the short Git commit hash. This hash is important to refer to and use in the next step.
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.
5. When the previous action has completed, you can deploy to your server with the following manually triggered action named "Deploy".
a) You will be required to select the environment that you wish to deploy to.
b) You will be required to enter the short Git hash that is tagged in the OpenCRVS Core release of choice.
c) You will be required to enter the short Git hash that is tagged in your country configuration image created by the previous "Publish image to Dockerhub" action.
Once the deployment is complete, wait a couple of minutes before browsing to OpenCRVS as it can take a little while for the Docker images to start up. If this is your first deployment, wait about 15 minutes as Docker must download these images from Dockerhub first.
Copy link