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 charts/bitnami/redis/values.yaml at main · bitnami/charts 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 charts/bitnami/postgresql/values.yaml at main · bitnami/charts 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

kubectl exec -it postgres-postgresql-0 -- bash

Login to postgres database instance using the psql client

psql -U postgres -h localhost

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

create user opensrp with encrypted password 'secretpassword';
alter role opensrp superuser; # ignore if using postgres v13 and above
create database opensrp;
grant all privileges on database opensrp to opensrp;

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

kubectl exec -it postgres-postgresql-0 -- bash

Login to postgres database instance using the psql client

psql -U postgres -h localhost

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

create user keycloak with encrypted password 'secretpassword';
create database keycloak;
grant all privileges on database keycloak to keycloak;

Create a values.yaml file to override the default configs with the above credentials. Refer to helm-charts/charts/keycloak/values.yaml at master · codecentric/helm-charts for additional configs.

---
replicas: 1

image:
  tag: "16.1.0"
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  rules:
    - host: keycloak-http.default.svc.cluster.local # if you are not using default namespace kindly update.
      paths:
        - path: /
          pathType: Prefix    
  tls:
postgresql:
  enabled: false

extraEnv: |
  - name: DB_VENDOR
    value: postgres
  - name: DB_ADDR
    value: postgres-postgresql.default.svc.cluster.local
  - name: DB_DATABASE
    value: keycloak
  - name: DB_SCHEMA
    value: public
  - name: PROXY_ADDRESS_FORWARDING
    value: "true"
  - name: DB_PORT
    value: "5432"
  - name: DB_USER
    value: keycloak
  - name: DB_PASSWORD
    value: secretpassword
  - name: KEYCLOAK_USER
    value: admin
  - name: KEYCLOAK_PASSWORD
    value: secretpassword
  - name: KEYCLOAK_FRONTEND_URL
    value: "http://keycloak-http.default.svc.cluster.local/auth/"

Run the following to install keycloak on your cluster.

helm repo add codecentric https://codecentric.github.io/helm-charts
helm repo update
helm install keycloak codecentric/keycloak -f ~/<dir>/keycloak/values.yaml

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

kubectl get pods

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.
1. 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.
  192.168.29.5 keycloak-http.default.svc.cluster.local
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:

helm repo add opensrp https://helm.smartregister.org
helm repo update

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

replicaCount: 1

image:
  tag: "v2.9.0-SNAPSHOT"

ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: opensrp-server-web.local
      paths:
        - path: /opensrp
          pathType: ImplementationSpecific
postgres:
  host: "postgres-postgresql.default.svc.cluster.local"
  port: 5432
  database: "opensrp"
  username: "opensrp"
  password: "secretpassword"

opensrp:
  cors_allowed_source: "*"

# external
redis:
  host: redis-master.default.svc.cluster.local
  port: 6379
  pool_max_connections: 25
  password: "secretpassword"

keycloak_json:
  realm: "<realm>"
  auth-server-url: "http://keycloak-http.default.svc.cluster.local/auth/"
  ssl-required: "none" # switch to external in a production setup
  resource: "<client-id>"
  confidential-port: 443
  credentials:
     secret: <client-secret>

vpa:
  enabled: false

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

helm install opensrp-server-web opensrp/opensrp-server-web -f ~/<dir>/opensrp-server/values.yaml

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.
1. 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.
  192.168.29.5 opensrp-server-web.local
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: GitHub - opensrp/helm-charts: OpenSRP community 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