How To Setup Opensrp Server Web on Kubernetes

The following steps will outline the process of deploying opensrp server web and its dependencies on kubernetes for a local environment.

Prerequisite:

Some knowledge on kubernetes.
Install kubectl.
- Allows you to run commands against Kubernetes clusters.
Install minikube. Dont use minikube in production!!
- It creates a kubernetes cluster we can use.
- One can use any other tool to bring up a cluster e.g microk8s, kops, kubespray, unoffical kubespray collection etc
- After you have successfully installed minikube enable the ingress addon.
  minikube addons enable ingress
Install helm. (Defacto package manager for k8s)

Setup Applications Used By Opensrp Server

Redis

Run the following to install redis on your cluster. Refer to https://github.com/bitnami/charts/blob/master/bitnami/redis/values.yaml for additional configs.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm install redis --set auth.password=secretpassword,cluster.enabled=false bitnami/redis

Postgresql

Run the following to install postgresql on your cluster. Refer to https://github.com/bitnami/charts/blob/master/bitnami/postgresql/values.yaml for additional configs. If deployed postgres before ensure the image tag matches your setup.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm install postgres --set auth.postgresPassword=secretpassword,auth.database=testdb,image.tag=14.1.0-debian-10-r80 bitnami/postgresql

Add opensrp database and user.

Login to the postgres pod

Login to postgres database instance using the psql client

Create keycloak user and make superuser so that the user has rights to create extensions.

Keycloak (For opensrp server web v2.2 and above otherwise skip this step)

We start with setting up keycloak database on the postgres database instance we created before.

Login to the postgres pod

Login to postgres database instance using the psql client

Create keycloak user and make superuser so that the user has rights to create extensions.

Create a values.yaml file to override the default configs with the above credentials. Refer to https://github.com/codecentric/helm-charts/blob/master/charts/keycloak/values.yaml for additional configs.

Run the following to install keycloak on your cluster.

To check if keycloak is up you could use the following command:

Check that the READY column for keycloak-0 is 1/1.

To access keycloak from your browser on a developement setup:

Get the minikube ip.
Then add the following entry in your /etc/hosts file in linux, for windows the hosts file should be located in C:\Windows\System32\drivers\etc.
1. 192.168.29.5 here is the minikube ip.
2. We must use keycloak-http.default.svc.cluster.local because of redirection during login. Not required if you have a public domain.

3. On your browser now you can load the following link.

On a production setup the assumption is that you will have a proper cluster certificate issuer and a public domain to use.

Additionally you will need to setup realms, users, clients, roles, and groups on keycloak. Instructions on how to do this is here.

Deploying Opensrp Server Web (for v2.2 and above refer here)

With redis , postgresql and keycloak running we can now deploy opensrp server.

To begin first fetch the helm chart repository:

Create a values.yaml file to override the default configs with credentials from postgres, redis and keycloak. Refer to https://github.com/opensrp/helm-charts/blob/main/charts/opensrp-server-web/values.yaml for additional configs.

Then run the following to install opensrp server web on your cluster.

Check that the READY column for opensrp-server-web pod is 1/1.

For opensrp-server-web to be in ready state all its services need to be healthy. Kindly refer to this documentation, that includes ensuring that keycloak is fully setup.

To access opensrp server web from your browser on a development setup:

Get the minikube ip.
Then add the following entry in your /etc/hosts file in linux, for windows the hosts file should be located in C:\Windows\System32\drivers\etc.
1. 192.168.29.5 here is the minikube ip.
On your browser now you can load the following link.

You are Done!!

Things to keep in mind.

Use a production ready tool to bring up a kubernetes cluster in a production setup.
Credentials should always be stronger and stored securely. Use helm secrets for this.
Opensrp Helm Chart Repositories: https://github.com/opensrp/helm-charts
For a functional web interface for the opensrp server kindly check this.
Update ingress configurations for production setup for external facing applications. Check this README for examples.
Ensure chart version is pinned during helm install --version <Chart-Version>.
Ensure image tag version is pinned for all the deployments.
Store all your configuration on values.yaml and secrets on secrets.yaml for all the deployments.
For production setup its recommended to setup postgres outside the cluster.

Documentation