4.3.2 HTTPS & Networking
Watch the videos above to understand the OpenCRVS network and how TLS is configured in OpenCRVS servers
Domain A records
Using your domain management system, A records will need to be created for all the services which are publicly exposed.
This also enables the Traefik SSL cert to be successfully generated by LetsEncrypt when using HTTPS or DNS challenge.
Either use a wildcard or create individual A records for your chosen domain name, with a TTL of 1 hour that forwards the URL to your manager server node's external IP address.
Option 1: Wildcard required A Records:
<your_domain>
*.<your_domain>
Option 2: Individual A Records:
<your_domain>
auth.<your_domain>
config.<your_domain>
countryconfig.<your_domain>
documents.<your_domain>
metabase.<your_domain>
minio.<your_domain>
minio-console.<your_domain>
ui-kit.<your_domain>
gateway.<your_domain>
kibana.<your_domain>
login.<your_domain>
openhim-api.<your_domain>
openhim.<your_domain>
register.<your_domain>
webhooks.<your_domain>
If using our Wireguard VPN:
vpn.<your_domain>
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.
LetsEncrypt HTTPS Challenge
Traefik config is required to be edited in your docker-compose files for your environment listed here, in order to configure the LetsEncrypt HTTPS challenge mechanism for SSL cert generation in development or qa environments:
- --certificatesresolvers.certResolver.acme.email=<your email address>
- --certificatesresolvers.certResolver.acme.storage=acme.json
- --certificatesresolvers.certResolver.acme.caserver=https://acme-v02.api.letsencrypt.org/directory
- --certificatesresolvers.certResolver.acme.httpchallenge.entrypoint=web
- --certificatesresolvers.certResolver.acme.httpchallenge=true
LetsEncrypt DNS Challenge
Traefik config is required to be edited in your docker-compose files for your environment in order to configure the LetsEncrypt DNS challenge mechanism for SSL cert generation in production or staging environments. LetsEncrypt supports APIs for the following providers:
In this example, Google Domains is the configured provider. The environment variable GOOGLE_DOMAINS_ACCESS_TOKEN is manually added to the Github environment as a secret.
environment:
- GOOGLE_DOMAINS_ACCESS_TOKEN=${GOOGLE_DOMAINS_ACCESS_TOKEN}
command:
- --certificatesresolvers.certResolver.acme.dnschallenge=true
- --certificatesresolvers.certResolver.acme.dnschallenge.provider=googledomains
- --certificatesresolvers.certResolver.acme.email=<your email address>
- --certificatesresolvers.certResolver.acme.storage=acme.json
Pre-existing TLS certificates
Traefik config is required to be edited in your docker-compose files for your environment in order to use pre-existing TLS certificates.
Once your environment is provisioned, manually add your certificate files into the /data/traefik/certs directory on your server so that they are picked up.
Create a file named certs.yaml in the infrastructure/traefik folder like this:
tls:
stores:
default:
defaultCertificate:
certFile: /etc/certs/<your combined leaf, intermediate & root, certfile>.crt
keyFile: /etc/certs/<your cert private key file>.key
certificates:
- certFile: /etc/certs/<your combined leaf, intermediate & root, certfile>.crt
keyFile: /etc/certs/<your cert private key file>.key
stores:
- default
Use the Traefik config below to access the cert.yaml file, remove any lines that start with "--certificatesresolvers.certResolver.acme" :
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /data/traefik/certs:/certs
- /opt/opencrvs/infrastructure/traefik/certs.yaml:/etc/traefik/certs.yaml
command:
- --providers.file.directory=/etc/traefik
- --providers.file.watch=true
If the certificate is different for each environment, you will have to edit the "Provision" Github Actions to write the contents of the .crt & .key files in the /data/traefik/certs directory on your server from new Github environment secrets you will manually have to create. In the file infrastructure/server-setup/tasks/traefik.yml, add these lines at the end of the file:
- name: Create crt file with variable content
copy:
dest: "/data/traefik/certs/cert.crt"
content: |
{{ssl_crt}}
owner: root
group: application
mode: 0644
when: ssl_crt is defined and ssl_crt | length > 0
- name: Create key file with variable content
copy:
dest: "/data/traefik/certs/cert.key"
content: |
{{ssl_key}}
owner: root
group: application
mode: 0600
when: ssl_key is defined and ssl_key | length > 0
Add these 2 new Github environment secrets SSL_CRT & SSL_KEY to the "Set variables for ansible in production environments" step in the file .github/workflows/provision.yml
ssl_crt: ${{ secrets.SSL_CRT }}
ssl_key: ${{ secrets.SSL_KEY }}
Last updated