# Quick Install

## Overview

This guide helps you deploy **DIGIT Complaints Management (CMS)** on AWS using GitHub Actions with a simplified process.\
It focuses solely on CMS-specific services and configurations, enabling faster setup and targeted deployment.

***

### Pre-Requisites

* AWS Account (with admin access)
* GitHub Organisation Account
* IAM User with `Access Key` and `Secret Key`
* Terraform uses `ap-south-1` (for now, hardcoded)
* SOPS for encrypting secrets
* Use a **private GitHub repo** to secure sensitive data

***

## Steps

{% stepper %}
{% step %}

### Create AWS Access Credentials

If not already done:

* Go to AWS Console → IAM → Users → Add user
* Assign **Admin access**
* Generate:
  * `AWS_ACCESS_KEY_ID`
  * `AWS_SECRET_ACCESS_KEY`

Example:

```bash
AWS_ACCESS_KEY_ID=A************FQ
AWS_SECRET_ACCESS_KEY=tqM************************+lfTt
AWS_REGION=ap-south-1
```

{% endstep %}

{% step %}

### Setup GitHub Repository

1. **Fork** the [repository](https://github.com/egovernments/Citizen-Complaint-Resolution-System) to your GitHub Org

   * Uncheck *“Copy the master branch only”*

   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdyf9_4NKUGe5mJ-jsN9NTbGgk1nWQB9EHO7nx1hg9Sb9bckZuoZ16uJI3K2rSFNpE7yJGotLxTuGKqoFDYeYM2DDtjoV46d6gceHbLP86L4ZOsUOjp31xpHQkuL64WVm3ZD2IDNQ?key=4vIdmt73mUh-cJZAdQrc2w)![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeSlF99j1Ge6JMm1NGivGaWimJr_SagifzDo0BzH9m_6P4hri3GNSL9TmV2_15Bm39AjfFvcTmsZtOCcCJpVjgOb1ncQy3_LXXh3JC8j9uR-SL1Xmie9VsanK1iBqv6isFZiCIIHQ?key=4vIdmt73mUh-cJZAdQrc2w)
2. Enable **GitHub Actions workflows** for the repo
3. Go to:

   * `Settings` → `Secrets and Variables` → `Actions` → `New Repository Secret`

   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeAIWDHkdpH2msSM9ts6ca8v7n_wtljAuKL2P6xfrstwi25oXFeNWmVhjMrnhDY_vRYh2fdOx-aVqgRZX2dJRmMDEG0PEn4-vA3mRKsy1zakUdGCh95tj7Xtm5iEHQ-doZoCnuYqw?key=4vIdmt73mUh-cJZAdQrc2w)

   * Add the below secrets: (refer to the table below)

   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXctX-lC2K1oKyL9yQWL-c5tXHqBlHvKBHxdsH6JguqtBDKXJSn3WfNhHqRzdt9LJNPcOj8RV_BjAgaPqdGcD6KusTfBfMcfyMEBKxGZ5kly8LivNMjYCZVIj1EC7WIE77NMi0tKYg?key=4vIdmt73mUh-cJZAdQrc2w)![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcfn7P2yuMHLdacERJsInNga7Lj7C5SPK4Uysb7xEZfDK2f1EU-1dM7t2bjK2SYup7fzVbB0GTcIxN_tpywIl1NV80Y5T8PcKHmZ91hflQ6dxbRAvdEocDBsAl4uqOHUQS2T_G5?key=4vIdmt73mUh-cJZAdQrc2w)

<table><thead><tr><th width="252.40234375">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>AWS_ACCESS_KEY_ID</code></td><td><code>&#x3C;GENERATED_ACCESS_KEY></code></td></tr><tr><td><code>AWS_SECRET_ACCESS_KEY</code></td><td><code>&#x3C;GENERATED_SECRET_KEY></code></td></tr><tr><td><code>AWS_REGION</code></td><td><code>&#x3C;AWS_REGION></code></td></tr><tr><td><code>AWS_DEFAULT_REGION</code></td><td><code>&#x3C;AWS_REGION></code></td></tr></tbody></table>
{% endstep %}

{% step %}

### Clone & Checkout Code

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXc1ZdnUVHOO81Qiehwl0vD-FCqpi-5MUi-KHs3myY-H-pBGAWrsK0tpwSuAJuC70efOHyu5HhVB-rboQnSJ3hx0Ol5vLYydD3iTX01TOIyXVWm4cL0Ti8ejVDQPCpeAgFCr5CLfyg?key=4vIdmt73mUh-cJZAdQrc2w)

```
git clone https://github.com/egovernments/Citizen-Complaint-Resolution-System.git
cd Citizen-Complaint-Resolution-System
git checkout master
```

* Open the repo in the code editor, or optionally use the GitHub[ web editor](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor) by replicating github.com with github.dev.
  {% endstep %}

{% step %}

### Generate SSH Key Pair

Use either of the two methods (for demo use only):

* Website: <https://8gwifi.org/sshfunctions.jsp>
  * Type: RSA 2048
  * Save the **public key** and **private key** separately

Sample Public Key:

```
ssh-rsa AAAAB3NzaC1yc2EAAAADAQA*************************************HBFUNjyMLpFltqwbsA*************************************MaMhX7Ou3*************************************PWHKx*************************************oVTBWxloXFQy/XFU*************************************W/QVdgs5xp+P5hhZgm9WpdN3Cz*************************************clYmUHoPCPwKIqElX2DZzYGJc*************************************y4gR
```

Sample Private Key:

```
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAue4+1*********************K7mGXRIv6enEP4lN/y9i287wsNBpg+IDGjIV************************************************************************************
+zrt79wBgG5vlGMoT1hysRDpxNNlDdimE6G8OHaCj6e5cwhXrMt1swKFUwVsZaFx
UMv1xVFU/OsrJ8v8***************************************************************** **********************Sd74a4d2h28pIEHNbrlvAVn7Zt9IDC
kgske+VBY+X0D2en1l8bt3Vdnn5xgcDQsPmp6GdoRfE2luJ6lAe+mdkCgYEA0wUj
tUHRH9sI3X86wZVREt*************************************************************** **********************************poTy6hNQr9IT2TsBckuN/qqockBR/j+iRap7lec3tJM
vdmMVP0Ed7GjBiSBVeHeHVg+Dt6+AqayWqU0hPkCgYB6o+bof7XnnsmBjvLVFO15
LlDiIZQFBtr7CriRDD2Nx************************************************************* ************************************TCaHk8CGmA+TXSKM9q7cTtMb6ythUQhZrpq 0EEY5TgQKBgQ*************************************************************8/PD+mT 5jFvon5Q==
-----END RSA PRIVATE KEY-----
```

{% endstep %}

{% step %}

### Configure Infrastructure Inputs

Go to: `Citizen-Complaint-Resolution-System/devops/infra-as-code/terraform/sample-aws/input.yaml`

Fill values for:

<table><thead><tr><th width="282.70703125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>cluster_name</code></td><td>Lowercase alphanumeric &#x26; hyphens only</td></tr><tr><td><code>public_ssh_key</code></td><td>Paste public key here</td></tr><tr><td><code>db_name</code></td><td>Alphanumeric</td></tr><tr><td><code>db_username</code></td><td>Alphanumeric</td></tr><tr><td><code>domain_name</code></td><td>Your domain (e.g. <code>demo.digit.org</code>)</td></tr><tr><td><code>terraform_state_bucket_name</code></td><td>Unique S3 bucket name</td></tr></tbody></table>
{% endstep %}

{% step %}

### Configure Application Secrets

Go to: `Devops/deploy-as-code/charts/environments/env-secrets.yaml`

Update:

* `db_password`Keep the password and the Flyway password the same.<br>
* `ssh_private_key` under `git-sync` (maintain indentation)

Also, add the **public key** to your GitHub account (for code syncing). Refer to the steps below to add the public key to your GitHub account.

1. Go to your profile icon in the top-right corner and click on settings. Refer screenshot below:\
   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeneXpO_l6q_0z_76BAxf_WVdsq-dj-2t8R4UkxDwStbAyETO2up9TSXQ-D7OWOlKFaa_LqQ912WsQzybW_cEPuapRPtpBsaeinRkdJWFYRhKo0OxSpFS3nkodcF9QSZ3mM3_9b?key=4vIdmt73mUh-cJZAdQrc2w)
2. Click on SSH and GPG keys, and click on the green button New SSH key. Refer screenshot below:\
   ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcTjelV16QtGjSxPdWTM8I9K6dLU8TryQcFis6AdC9c8OlGL4VfK72EpzRuD9TlG8Qq6hzFqdW9LW2vkiA02DrO7dEfGfo2IM_M3eMz9l5Euu0_5p9hT7z8WwTvIyMvwBRpLXvrxw?key=4vIdmt73mUh-cJZAdQrc2w)
3. Add the public key in the key section. You can add the title name as my-public-key or something similar.
   {% endstep %}

{% step %}

### Trigger Deployment

Push your changes to the **master** branch.

Then:

* Go to GitHub → Actions tab

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXfGyZbILfImfbAFmpyHY7gHTmjemMlPvFkL62IBWRygcpb-zxIcmXREtGToeieaEIvTG-92BJ7B7D24Trbz1hwum5BVMRPr3jV2_BkhenwX3fiD_MffH9LAl6fZ9w_4958SuciXYQ?key=4vIdmt73mUh-cJZAdQrc2w)

* Click on DIGIT Install workflow
* Click on the Run Workflow button
* Select the master branch&#x20;
* Click on the Run Workflow button (in green)
* Open the Actions tab in your GitHub account to view the workflow. You should see that the workflow has started and the pipelines have been completed successfully.

  ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcyCAWIrYswBcPzoyhmgX7i5LdIIOb01_a8wFSTJDzoR4t4e39gSw7nW-5pYQdS5iowNn6cr1hNxXQfDD70i8jMjqpw5FaR6wAlhigzB2lLEyL2cbvMuw16-Lj5mQqfYi17TtAijQ?key=4vIdmt73mUh-cJZAdQrc2w)

A GitHub Actions workflow is triggered after committing the inputs. This shows that your setup is correctly configured and your application is ready for deployment. Watch the workflow output for any errors or success messages to confirm everything is functioning as expected.
{% endstep %}

{% step %}

### Setup Kubeconfig

**Install AWS CLI (If not already installed)**\
Open the terminal. Run the following command, which you have installed on the AWS CLI, and use the provided credentials. (Provide the credentials and leave the region and output format blank).

`curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"`

`unzip awscliv2.zip`

`sudo ./aws/install`

Verify installation:\
`aws --version`

{% hint style="info" %}
**Note:** Ensure the profile name provided in the commands below matches the AWS profile used in the Terraform scripts.
{% endhint %}

Ensure AWS CLI is configured:

```bash
aws configure --profile digit-quickstart-poc
AWS Access Key ID []:<Your access key>
AWS Secret Access Key []:<Your secret key>
Default region name []: ap-south-1
// Setting profile
export AWS_PROFILE=digit-quickstart-poc
```

The above will create the following file on your machine under the user's home directory. `/path/to/user/home/.aws/credentials`

<img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXc-WZSxy0PsYxi1JGcFSsgdLLdAoSnUVCoY1JjrUnCCQ8Ko0gFcep5hoWGs6WbL5kx8ycJlylu-sNwJeT0SdgIVbTKJ7zLgebHVAd_hTX8kKOUOtMr8qck6FWVD85AgCE5ChXcp-w?key=4vIdmt73mUh-cJZAdQrc2w" alt="" data-size="original">

{% hint style="info" %}
Additionally, ensure your AWS CLI is correctly configured by referring to the official AWS documentation on Configuring the AWS CLI - AWS Command Line Interface. Confirm your AWS credentials are correctly set by executing:

If not, create the profile using:

`aws configure --profile <profile_name>`

Run the below command to export AWS Credentials

`export AWS_PROFILE=<profile_name>`
{% endhint %}

Proceed only after verifying the correct configuration of your credentials. For any uncertainties on how to set up the credentials, consult the AWS documentation for detailed instructions. To check if credentials are properly set, run the command:

`aws configure list --profile <profile_name>`

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdIxvzlzgTj8j8J4y7R4CSyuVmchDeosYoFeCtl-hou_GvSPvh3MSgqvnM9V5Szl6yZaXyG0S-NR_ekDkT57bh8CkG44HIoS9tuL3Iz2MEOqpvPqpGwk3k4XW-v7uwUkNtjWK8JqQ?key=4vIdmt73mUh-cJZAdQrc2w)

Get the Kubernetes configuration and verify that you can connect to the cluster by running the command below.

```
aws eks --region ap-south-1 update-kubeconfig --name <cluster_name>
kubectl config use-context <cluster_name>
kubectl get nodes
kubectl get pods -A
```

{% endstep %}

{% step %}

### Verify Pods Status

First ensure that all pods in the namespace are running as expected. Use the following command to list all pods:

```bash
kubectl get pods -n <namespace>
```

* Verify that the **STATUS** column shows `Running` or `Completed`.
* Ensure there are no pods stuck in states like `CrashLoopBackOff`, `Init:Error`, or `Init:ConfigMapKeyMissing`.

✅ Example check:

```bash
kubectl get pods -n egov
```

If any pod is failing, proceed with the troubleshooting steps outlined in the FAQ sections.

### Note: Default Data Seeding

The **`default-data-handler`** service is responsible for seeding default data during system initialisation. This includes:

* **MDMS** data
* **Localization** data
* **Boundary** data

The service attempts to insert this data by invoking relevant APIs at startup.

#### Important

* If any of the dependent services (e.g., MDMS, Localisation, Boundary) are **not up and running** during initialisation, the default data will **not be loaded**.
* Once the required services are available, you must **restart the `default-data-handler` service** to trigger data seeding again.
* **Restart the gateway service**. Sometimes the gateway service may already be running while other services are still starting up. If those services come up later, they might not get registered with the gateway. As a result, trying to access their APIs can throw a **404 error**. To avoid this issue, the gateway service needs to be restarted. Use below command to restart a gateway service.

```
kubectl rollout restart deployment gateway -n egov
```

{% endstep %}

{% step %}

### Domain Setup

To get the domain:

```bash
kubectl get svc ingress-nginx-controller -n backbone -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
```

Example output:

```
ae210873da6f.ap-south-1.elb.amazonaws.com
```

➡️ Add this as a **CNAME record** in your domain provider settings.
{% endstep %}

{% step %}

### Log in to DIGIT

```
https://<your-domain>/digit-ui/employee
```

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXed24S6SD982CgbybOfcnms4MEIDCU2ReqbBwXEHNJ01UK703JOzdAcrTJoK-hY-puny_Qf5_awYBICEuaMZmNm2SPfSi7XmvuFewsWP4E6afdK6BGEa_-pM3ISdPHLgTY4tJvG8w?key=4vIdmt73mUh-cJZAdQrc2w)

Log in using the username/password from `env-secrets.yaml`.
{% endstep %}
{% endstepper %}

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXc-WZSxy0PsYxi1JGcFSsgdLLdAoSnUVCoY1JjrUnCCQ8Ko0gFcep5hoWGs6WbL5kx8ycJlylu-sNwJeT0SdgIVbTKJ7zLgebHVAd_hTX8kKOUOtMr8qck6FWVD85AgCE5ChXcp-w?key=4vIdmt73mUh-cJZAdQrc2w" alt=""><figcaption></figcaption></figure>

***

## Clean Up (Uninstall DIGIT)

To destroy the infrastructure:

1. Go to GitHub → Actions → `DIGIT-Install workflow`
2. Click `Run workflow`
3. In the input box, type: `destroy`
4. Monitor the job status

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdn9aFk4nolBaXqT5UWStis_jsW15ktYUKVxLeDKjd_zODQbS5mj4ilhbZIam-w7BXAAu62KeVsapLL44c-uPQ9rQS_C6yQvGupMxAqoUSL8glC4aEQwcTaLLzR_J1_2LqLtE76?key=4vIdmt73mUh-cJZAdQrc2w)

✅ This will remove all DIGIT infrastructure via Terraform.

{% hint style="info" %}
💡 **Note**: If using a different branch (e.g. `digit-install`), ensure it’s mentioned in the workflow YAML under `branches:` the section.
{% endhint %}

***

## Summary

| Step           | What to Do                         |
| -------------- | ---------------------------------- |
| IAM Setup      | Create IAM user with keys          |
| GitHub Secrets | Add 4 AWS-related secrets          |
| Key Generation | Create SSH key pair                |
| Infra Inputs   | Fill `input.yaml` with your values |
| App Secrets    | Add `db_password` and SSH key      |
| Deployment     | Push changes → GitHub workflow     |
| KubeConfig     | Setup CLI and connect to cluster   |
| Domain Mapping | Add CNAME to DNS                   |
| Cleanup        | Use `destroy` in GitHub workflow   |