The following steps will outline the process of deploying opensrp server web and its dependencies on kubernetes for a local environment.
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)
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 |
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
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; |
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 https://github.com/codecentric/helm-charts/blob/master/charts/keycloak/values.yaml 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.
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
.
192.168.29.5
here is the minikube ip.
192.168.29.5 keycloak-http.default.svc.cluster.local |
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.
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 https://github.com/opensrp/helm-charts/blob/main/charts/opensrp-server-web/values.yaml 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.
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
.
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!! |
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.