Guides

On premise setup of Avni without cloud services

Suggest Edits

DRAFT (following features are under development)

Currently, Avni only supports single-tenant setup in an on-premise setup. Technically there is a small step to support a multi-tenant setup also.

Avni uses cloud services like AWS Cognito, S3, and Route53 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 Avni simple. In the future, Avni will continue to use such services - for the same reasons. But since Avni is an open-source project, some users of Avni want to deploy it in their own data centers. Avni project will provide 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 Avni 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, etc - as they are available at so many places on the Internet.

Open-source alternatives supported by Avni.
Cognito -> KeyCloak
S3 -> Minio
Route53 -> Ngnix

Setting up KeyCloak manually

  • Download and Install JDK 18, as instructed here
  • Download and install keycloak 18 https://github.com/keycloak/keycloak/releases/download/18.0.1/keycloak-18.0.1.zip preferrably in /opt/keycloak-18.0.1/ 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
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.
    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 
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.avniproject.org --staple-ocsp -m <user_email> --agree-tos
mkdir -p ${HOME}/.keycloak/certs
cd 
sudo cp /etc/letsencrypt/live/keycloak-staging.avniproject.org/fullchain.pem ${HOME}/.keycloak/certs/public.crt
sudo cp /etc/letsencrypt/live/keycloak-staging.avniproject.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 Avni user's authentication details are present in Keycloak, whereas application-specific details are in the Avni database. To ensure consistency and linking of a user entity across these two databases all user modification/creation calls are routed through the Avni server. In order to do this, the Avni 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 avni-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:
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=admin
KEYCLOAK_HOME=/opt/keycloak-18.0.1/
  • Logout user and log back in

Start keycloak

  • Option 1: with configuration passed as CLI parameters:
    bin/kc.sh start --hostname-strict=false --db-url-host localhost --db-username keycloak --db-password password --https-certificate-file=./domain.crt --https-certificate-key-file=./domain.key
  • Option 2: with configurations specified in keycloak conf file conf/keycloak.conf:
    nohup $KEYCLOAK_HOME/bin/kc.sh start &
    Find more details here.

Setup Super Admin User

Assuming that you have started avni-server after deployment at least once, you should have an admin user in your database who doesn't belong to any organization and is a super admin. Before you use the web app to log in as this user and create other organizations and users - this first user needs to be added to keycloak.

In Keycloak you can add a user in the same realm (not master). For this user please note the following:

  • User is enabled
  • Email is marked as verified
  • Add a custom attribute called custom:userUUID and in the value provide the UUID value from the Avni database for the admin user (present in the users table).

Setup Avni Server to use Keycloak

Avni server by default uses Cognito, hence you need to set up the following environment variables to make it work with Keycloak.

export OPENCHS_KEYCLOAK_CLIENT_SECRET=dsfhdfdsfh323
export OPENCHS_KEYCLOAK_SERVER=https://keycloak.example.com
export OPENCHS_KEYCLOAK_ENABLED=true

Test

Launch the avni web app and you must be able to log in using the admin user and create organization etc.

A few more notes

Even though you are not using Cognito you may see the field disabledInCognito in Keycloak user attributes and in the REST API contract exchanged between the avni web app and the avni server.

Setting up MinIO server manually

Refer MinIO Quickstart guide to setup the MinIO server on Ubuntu Machine - https://docs.min.io/docs/minio-quickstart-guide.html

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
  • Generate SSL certificates
    sudo certbot certonly --standalone -d minio-staging.avniproject.org --staple-ocsp -m <user_email> --agree-tos
  • Configure Minio server to use the SSL certificates
sudo cp /etc/letsencrypt/live/minio-staging.avniproject.org/fullchain.pem ${HOME}/.minio/certs/public.crt
sudo cp /etc/letsencrypt/live/minio-staging.avniproject.org/privkey.pem ${HOME}/.minio/certs/private.key
sudo chown ubuntu:ubuntu ${HOME}/.minio/certs/public.crt
sudo chown ubuntu:ubuntu ${HOME}/.minio/certs/private.key
sudo setcap 'cap_net_bind_service=+ep' ./minio
  • You also need to set two environment variables for Minio web console app to correctly redirect to server.
    Add below lines to /etc/environment file and logout and login back to the machine.
MINIO_BROWSER_REDIRECT_URL="https://minio-staging.avniproject.org"
MINIO_SERVER_URL="https://minio-staging.avniproject.org:442"
  • Start minio server as a background process
    cd ~/minio
    nohup ./minio server ./data --address ":442" --console-address ":443" >> /var/log/minio/minio.log 2>&1 &

Updated 9 months ago