On premise setup of Sakhi2.0 without cloud services

Sakhi2.0 uses cloud services like AWS Cognito, S3, and ALB for user management, file storage, and reverse proxy respectively - to implement certain functional and technical features. Usage of these services (and other non-functional components like RDS) makes the hosting and operations of Sakhi2.0 simple. In the future, Sakhi2.0 will continue to use such services - for the same reasons. But since Sakhi2.0 is an open-source project, some users of Sakhi2.0 want to deploy it in their own data centers. Sakhi2.0 project therefore also supports integration with open source alternatives to the functional services, and provide automation scripts, and documentation.

While elsewhere in this documentation you may find some Linux commands specific to centos, but Sakhi2.0 is shifting all its OS usage to Ubuntu 20-04. Hence any commands in this document are for Ubuntu.

As we have mentioned elsewhere in the documentation - unless required here we have not put the documentation for installation or setup of standard software packages like Postgres, Java, Ansible, etc - as they are available at so many places on the Internet.

Open-source alternatives supported by Sakhi2.0 are as follows:

Note: Its important to note that, opting between Cognito or Keycloak for IdentityManagement and S3 or Minio for Storage management is a one-time choice. Once configured, switching to the other alternative could result in access / data loss.

Pre-requisites
Knowledge
Familiarity with Linux Operating system
Shell Command-line
Ansible
SSH
Basic understanding of Web applications
Work-machine
A Ubuntu / MacOS Work-system which has following installed:

Python
Git
Ansible
Target On-premise server specificatins
Target system with 5 different compute nodes, for following purpose with these minimum configurations:

Sakhi2.0-Server (Including webapp and rules-server) : 2 vCPU, 4 GB RAM
Keycloak : 2 vCPU, 4 GB RAM
Minio : 2 vCPU, 4 GB RAM, with 200 GB storage
Postgres Server : 2 vCPU, 4 GB RAM, with 100 GB storage
Reverse-Proxy : 1 vCPU, 2 GB RAM
Clone the following GIT Repositories
Sakhi2.0-client : Used for generating an Sakhi2.0-client APK to use with rest of your Sakhi2.0 application
Sakhi2.0-infra : Used for performing installation of all the remote components of Sakhi2.0 application

Preparation

In Sakhi2.0, we make use of Ansible scripts available in "Sakhi2.0-infra" repository to setup Sakhi2.0 on an On-premise environment.

You may install Ansible on your work-system, by following instructions specified here

Navigate to "Sakhi2.0-infra" repository, "configure" directory and perform following steps

Search and replace all instances of "security.lfe.Sakhi2.0project.org" in "Sakhi2.0-infra" repository with your Company/project's domain name. Ex: "dev.mycompany.org"

Create a file "configure/group_vars/onpremise-secret-vars.yml" in "Sakhi2.0-infra" repository using "configure/group_vars/onpremise-secret-vars.template.yml" as the template and set appropriate values for all values enclosed in "{{}}"

Invoke the Encrypt command to save the newly created file, using your own encrytion_key file

make encrypt VAULT_PASSWORD_FILE=~/config/infra-pwd-file
To be able to read encrypted file content decrypt it using, decrypting will overwrite the contents of "configure/group_vars/onpremise-secret-vars.yml", therefore if there are changes in "configure/group_vars/onpremise-secret-vars.yml", encrypt it and commit before invoking the decrypt command

make decrypt VAULT_PASSWORD_FILE=~/config/infra-pwd-file
We then use this same encrytion_key file while invoking ansible playbooks for "Sakhi2.0" applications installation

app_zip_path=~//rules-server/ make rules-server-onpremise VAULT_PASSWORD_FILE=~/config/infra-pwd-file

Database

PostgreSQL Database (version 12.x)
Install postgresql-server, postgresql-contrib packages
Initialize the database and start
Change postgres login access from peer to trust - Edit /var/lib/pgsql/VERSION/data/pg_hba.conf. As in line 2 and 9 of this file.
Restart postgres - sudo systemctl restart postgresql-VERSION
Create OpenCHS database, user and install extensions

Keycloak

Automated setup of KeyCloak using Ansible

We have ansible playbook to automate setup of Keycloak of "21.0.2" version for staging environment. This could be modified to suit change in target servers, Keycloak-version and credentials as per requirement.

On your machine, clone Sakhi2.0-infra repository and install ansible and other dependencies required
Navigate to "configure" folder with-in the repository and trigger following "make" command with credential values as args:
keycloak_db_password=<db_pwd> keycloak_admin_pwd=<admin_pwd> keycloak_admin_api_secret=<admin_api_secret> make keycloak-staging
Above command internally invokes following ansible playbook command:
KEYCLOAK_DB_PASSWORD=$(keycloak_db_password) KEYCLOAK_ADMIN_PWD=$(keycloak_admin_pwd) KEYCLOAK_ADMIN_API_SECRET=$(keycloak_admin_api_secret) ansible-playbook staging_keycloak_servers.yml --tags=keycloak -i inventory/staging
For setting up different version of Keycloak on any-other machine in a different environment, update the inventory file and/or targets and/or vars correspondingly

Setting up KeyCloak manually
Download and Install JDK 18, as instructed here
Download and install keycloak 21 https://github.com/keycloak/keycloak/releases/download/21.0.2/keycloak-21.0.2.zip preferrably in /opt/keycloak-21.0.2/ folder.
Install Postgres 12 (unless you have a Postgres server running already which can be reused for Keycloak). You may use the instructions here
Create a user and database in the Postgres server

PL/pgSQL

create user keycloak with password 'password';
create database keycloak;
GRANT ALL PRIVILEGES ON database keycloak TO keycloak;

Configure keycloak to work with Postgres
bin/kc.sh build --db postgres

Create a certificate, pem file, to run keycloak on TLS

This is recommended even if you are will be putting Nginx or Apache as a reverse proxy. We do not recommend SSL termination - as that will means an unencrypted password in the internal network visible to production support engineers.

Option 1: Commands for self-generated keys and certificates are given below. You should decide whether self-generated keys and certificate is the right option for you.

Shell

openssl req -newkey rsa:2048 -nodes -keyout domain.key -out domain.csr
openssl x509 -signkey domain.key -in domain.csr -req -days 365 -out domain.crt

Option 2: Commands to generate keys and certificates using Certbot

Shell

sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo apt install net-tools
sudo certbot certonly --standalone -d keycloak-staging.Sakhi2.0project.org --staple-ocsp -m <user_email> --agree-tos
mkdir -p ${HOME}/.keycloak/certs
cd
sudo cp /etc/letsencrypt/live/keycloak-staging.Sakhi2.0project.org/fullchain.pem ${HOME}/.keycloak/certs/public.crt
sudo cp /etc/letsencrypt/live/keycloak-staging.Sakhi2.0project.org/privkey.pem ${HOME}/.keycloak/certs/private.key
sudo chown ubuntu:ubuntu ${HOME}/.keycloak/certs/public.crt
sudo chown ubuntu:ubuntu ${HOME}/.keycloak/certs/private.key

A basic starter realm can be imported into keycloak by using bin/kc.sh import --file=basic_realm.json. Note the server must be stopped. The realm which we will use is called On-premise (not master). You can change the name of the realm before/after import too - the name is configurable.
Each Sakhi2.0 user's authentication details are present in Keycloak, whereas application-specific details are in the Sakhi2.0 database. To ensure consistency and linking of a user entity across these two databases all user modification/creation calls are routed through the Sakhi2.0 server. In order to do this, the Sakhi2.0 server needs client access to Keycloak's realm. This client's name is admin-api, you should be able to find it in the Clients tab. Since in the above step you have imported a common realm file, you must regenerate the client secret. For this, open the admin-api client go to the credentials tab, and then Regenerate Secret. This secret value will be provided to the Sakhi2.0-server as described below.
If you are running keycloak such that you cannot log in via browser from localhost as admin, then you can set two environment variables for first-time access. You should choose a strong password. Also, set KEYCLOAK_HOME to point to the Keycloak installation directory.
Add below lines to /etc/environment file:

Shell

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=
KEYCLOAK_HOME=/opt/keycloak-21.0.2/

Logout user and log back in