Quick Setup

Owned by Nikhil Mulinti
May 13, 2024
9 min read

DIGIT Quickstart is recommended to jump-start with minimal DIGIT services to get a sense of the various installation steps and system requirements.

Overview

DIGIT Quickstart setup helps in installing the DIGIT Infra on a local machine/VM. This installation is not meant for production use. However, this quick setup flow familiarizes users with the key production-grade setup processes.

Quickstart is recommended for basic infra types like a local machine, setting up on a single VM, etc. This setup creates a lightweight Kubernetes (k3d ) cluster which does not require a full-fledged cloud setup or multiple VMs. Refer to the open-source project k3d to learn more. Install the k3d on a local or on a VM once all the pre-requisites and hardware requirements specified below are met.

Hardware Pre-requisites

To install k3d, ensure the instance meets the following hardware requirements to ensure sufficient CPU and memory in default systems and meets the DIGIT setup requirement.

Apart from the regular system usage, DIGIT requires the following dedicated CPU/Memory specs:

  • An admin/sudoer access to proceed

  • OS: Ubuntu 18.04 or Debian 10 or Windows 10 or Mac OSX

  • Local machine or VM or bare metal

  • 16 GiB of RAM (recommend 20+)

  • 30 GiB of HDD (recommend 40+)

  • NAT or Bridged networking with access to the internet

Required Checks

Before proceeding with DIGIT quick setup - Check the machine's remaining CPU/Memory capacity. Use the following commands to fetch the memory details. The commands vary from OS to OS. Click on the specific OS option below to view the instructions.

Linux - On Terminal

free -m

Note: The output of the commands in the above links provides the total memory/CPU and unused/free/available memory/CPU details. Make sure the unused/free/available memory matches the following specs:

  • Memory: 8GB

  • CPU: >30%

Quickstart Setup

Once the above prerequisites are met, proceed with the following steps -

Setting Up Kubernetes Cluster On A Single Machine/VM

Click on the relevant environment option (local machine/VM/Cloud AWS)below to start with the setup. Before proceeding with the setup, make sure to check the hardware requirement of the selected environment.

On local machine/VM

Pre-requisites

  • Linux distribution running in a VM or bare metal

    1. 1.

      Install curl, wget git, and tar (if they're not already installed):

      • sudo apt-get install curl git wget tar

    2. 2.

      Install Docker

    3. 3.

      Install kubectl on Linux

    4. 4.

      Open terminal and Install k3d(v4.4.8) on Linux using the below command

      • wget -q -O - https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | TAG=v4.4.8 bash

  • OSX or Mac

    1. 1.

      Docker Desktop local Kubernetes cluster enabled

    2. 2.

      Install kubectl on Mac

    3. 3.

      Install k3d on Mac, on terminal use curl command

    4. 4.

      Homebrew (Homebrew is available for MacOS) using the below command to install curl

    brew install curl

    curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | TAG=v4.4.8 bash

  • Windows 10 or above

    1. 1.

      Admin access to follow the steps

    2. 2.

      Docker Desktop for windows need to be installed ( make sure wsl is installed to run Docker Desktop )

    3. 3.

      Install kubectl on Windows

    4. 4.

      Install Chocolatey package manager for windows

    5. 5.

      Install GitBash as an alternative command prompt that allows most of the Linux commands on windows.

    6. 6.

      Install k3d(v4.4.8)

Create Lightweight Kubernetes Cluster

Ensure that the docker is running and you have the admin privileges for the device. Run the following in the terminal/command prompt.

Note: Make sure the k3d is already installed as part of the pre-requisites.

Start with the setup of the lightweight Kubernetes cluster on your local machine/VM. Execute all the instructions as admin/root/sudoer to give the installer full access to provision the required system resources/folders etc.

  1. 1.

    Create the "Kube" directory in the desired place (ensure you use the right dir path if it is different from the example) and change permission. This is used as k3d cluster persistent storage to store metadata and container logs.

    • For Linux/Mac

      • cd ~

        mkdir kube

        chmod 777 kube

        cd kube

        pwd #copy the path you get here. Provide an absolute path to below k3d cmd, by replacing "/home/<user_name>/kube" with your directory path

    • For Windows

      • cd D:\

        mkdir kube

        wsl chmod -R 777 kube

        cd kube

        pwd #copy the path you get here. Provide an absolute path to below k3d cmd, by replacing "/home/<user_name>/kube" with your directory path

  2. 2.

    Create a k3d cluster with a single master node and 2 agents (Worker Nodes) and mount the above-created directory (for data persistence). Here's where it stores all the metadata and persists the logs of the workloads.

    • k3d cluster create --k3s-server-arg "--no-deploy=traefik" --agents 2 -v "/home/<user_name>/kube:/kube@agent[0,1]" -v "/home/<user_name>/kube:/kube@server[0]" --port "80:80@loadbalancer"

    NOTE: Update "/home/<user_name>/kube" path in the above cmd with your respective absolute path.

  3. 3.

    Once the cluster creation is successful, get the kubeconfig file, that enables you to connect to the cluster.

    • k3d kubeconfig get k3s-default > myk3dconfig

      export KUBECONFIG=<path-to-your-kube_config>

    • kubectl config use-context k3d-k3s-default --kubeconfig=myk3dconfig

  4. 4.

    Verify the cluster creation by running the following commands from your local machine where the kubectl is installed. It provides the sample output as below if everything works fine.

    • kubectl cluster-info

      OutPut

      Kubernetes control plane is running at https://0.0.0.0:33931

      CoreDNS is running at https://0.0.0.0:33931/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

      Metrics-server is running at https://0.0.0.0:33931/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

    • k3d cluster list

      OutPut

      NAME SERVERS AGENTS LOADBALANCER

      k3s-default 1/1 2/2 true

    • kubectl get nodes

      OutPut

      NAME STATUS ROLES AGE VERSION

      k3d-k3s-default-agent-0 Ready <none> 3d18h v1.21.1+k3s1

      k3d-k3s-default-agent-1 Ready <none> 3d18h v1.21.1+k3s1

      k3d-k3s-default-server-0 Ready control-plane,master 3d18h v1.21.1+k3s1

    • kubectl top nodes

      OutPut

      W0625 07:56:24.588781 12810 top_node.go:119] Using json format to get metrics. Next release will switch to protocol-buffers, switch early by passing --use-protocol-buffers flag

      NAME CPU(cores) CPU% MEMORY(bytes) MEMORY%

      k3d-k3s-default-agent-0 547m 6% 1505Mi 9%

      k3d-k3s-default-agent-1 40m 0% 2175Mi 13%

      k3d-k3s-default-server-0 59m 0% 2286Mi 14%

If the above steps are completed successfully, your cluster is now up and running ready to proceed with the DIGIT deployment.

 

  1. Deployment

DIGIT Deployment On k3d

Now that the Infra setup is complete, the next step is the deployment of DIGIT services. The pre-requisites for deployment are listed here.

What we'll deploy in Quickstart:

  • DIGIT's core platform services

  • Governance Service/s

DIGIT uses golang scripts to simplify the deployment process - an automated way by leveraging helm package manager to deploy the containerized services onto Kubernetes. Ensure that the below prerequisites are met before you proceed.

1. Pre-requisites

  1. 1.

    Install golang (required v1.13.3). Use these links to install- Linux or Windows or Mac​

  2. 2.

    All DIGIT services are packaged using helm charts, Install helm using the link

    Installing Helm​

  3. 3.

    ​kubectl is a CLI to connect to the Kubernetes cluster on your machine

  4. 4.

    Install CURL for making API calls

  5. 5.

    ​Install Visualstudio IDE Code for better code visualization/editing capabilities

  6. 6.

    ​Install Postman to run digit bootstrap scripts

2. Deployment Configuration

  1. 1.

    Clone the following DIGIT Devops GitRepo. You may have to install git and then run git clone on your machine.

  2. 2.

    After cloning the repo CD into the folder DIGIT-DevOps, type the "code" command. This opens the visual editor and the DIGIT-DevOps repo files.

    • cd DIGIT-DevOps

      code .

  3. 3.

    Create a deployment config file. Use the following template to update any custom values to be changed (if you know the impact). Run it as is for the quickstart. Navigate to the following file in your local repo:

    DIGIT-DevOps/deploy-as-code/helm/environments

Deployment config template

4. Add the following entries in your host file /etc/hosts depending on your OS, instructions can be found below.

Add the following lines to the host file in your local machine. Save and close the file.

  • 127.0.0.1 quickstart.local.digit

Those who are using Cloud VM/Instance - add the below entry to the host file in your local machine/laptop. Replace <Public_IP> with your VM/Instance Public IP.

  • <Public_IP> quickstart.local.digit

 

3. Deployment

Once the deployment config is ready run the following command. Provide the necessary details and the interactive installer will take care of the rest.

  1. 1.Run the deployer go script from the following directory:

export KUBECONFIG=<path-to-your-kube_config> cd DIGIT-DevOps/deploy-as-code/egov-deployer sudo go run digit_setup.go #Be prepared for the following questions Are you good to proceed? Please enter the fully qualified path of the kubeconfig file Which DIGIT Version You would like to install, Select below Select the DIGIT modules that you want to install, choose Exit to complete selection Choose the target env files that are identified from your local configs Are we good to proceed with the actual deployment? All Done.

 

2. Check all the pods are running and ready using the below command

kubectl get pods -A

 

Note: If Kafka and zookeeper pods go into crashloopbackoff state due to a permission issue, use the below commands.

For Linux/Mac

cd ~ sudo chmod -R 777 kube kubectl delete pod kafka-0 -n kafka-cluster --kubeconfig=<your_kubeconfig_path> kubectl delete pod zookeeper-0 -n zookeeper-cluster --kubeconfig=<your_kubeconfig_path>

3. Test the Digit application status in the command prompt/terminal using the command below:

curl -Is http://quickstart.local.digit/employee/login | head -n 1 OutPut: HTTP/2 200

 

4. Post-Deployment Steps

Post-deployment the application is now accessible from the configured domain.

For initiating PGR employee login, create a sample tenant, city, user to login and assign LME employee role through the seed script.

  1. 1.

    Perform the kubectl port-forwarding of the egov-user service running from Kubernetes cluster to your localhost. This provides access to the egov-user service directly and allows the service to interact with the API.

 

  1. Seed the sample data

  • Ensure you have the postman to run the following seed data API. If not, run the Install postman on your local machine.

  • Import the following postman collection into the postman and run it. This has the seed data that enable sample test users and localisation data.

https://raw.githubusercontent.com/egovernments/DIGIT-DevOps/quickstart/deploy-as-code/bootstrap_scripts/seed_data.json

 

image-20240513-051109.png

 

image-20240513-051118.png

 

To test the Kubernetes operations through kubectl from the local machine, execute the below commands.

 

This completes the setup of DIGIT Infra, deployment and installation of the DIGIT-PGR module.

Paste the below link in the browser.

 

Use the below credentials to login into the complaint section:

Username: GRO

Password: eGov@4321

City: CITYA

 

5. Destroying the Setup

Use the instructions below to destroy the setup once you are done exploring or experiencing the DIGIT platform using the quickstart approach.

OutPut

NAME SERVERS AGENTS LOADBALANCER

Deleting the cluster automatically deletes all the DIGIT deployment components and frees up the system resources.​​