Local Setup CCRS Service

Overview

This guide provides step-by-step instructions to set up the pgr-services module on your local system. It follows the official LOCALSETUP.md from the egovernments/Citizen-Complaint-Resolution-System repository.

---

Why and When You Need a Local Setup of CCRS Services

Setting up the CCRS (Citizen Complaint Resolution System) locally is an essential step for developers, QA engineers, and technical stakeholders working on the eGov platform. Below is an overview of the key reasons and scenarios when a local environment becomes necessary.

✅ Why Set Up CCRS Locally?

1. Development and Customisation

   • Local setup enables developers to modify and test new features, enhancements, and bug fixes in isolation before pushing code to shared environments.

   • It allows customisation specific to a state, region, or integration requirement without affecting other teams.

2. Faster Debugging and Troubleshooting

   • Logs, breakpoints, and real-time inspection tools become available in a local IDE, greatly reducing turnaround time for issue resolution.

   • Easier to isolate problems that may not be reproducible in remote or containerised environments.

3. Better Control Over the Environment

   • Developers can control dependencies, database state, and configuration files (e.g., application.properties, MDMS), and simulate scenarios like failures or latency.

4. Offline Development Capability

   • A fully configured local environment allows productive development even in cases of restricted or no internet access to cloud/dev environments.

5. Learning and Experimentation

   • New team members can explore the architecture, flow, and modules safely.

   • Allows sandbox experimentation with business logic, workflows, and integrations like Elasticsearch, Kafka, MDMS, etc.

Steps

1

Clone the Core Service Repository

Clone the municipal-services repository (which contains pgr-services):

git clone [email protected]:egovernments/Citizen-Complaint-Resolution-System.git

Go to the root directory of ccrs-services using the command below:

cd backend/pgr-services

2

Install Required Dependencies

Ensure the following services/tools are installed and running on your local system before starting the CCRS backend.

1. PostgreSQL – Relational database for storing structured data 📄 Official Documentation 💻 Download & Install

2. Apache Kafka – Message broker for producer-consumer event communication 📄 Official Documentation 💻 Download & Install

3. Elasticsearch – Search and analytics engine for indexing and querying data 📄 Official Documentation 💻 Download & Install

3

Start or Access Dependent Services

The pgr-services module depends on several other DIGIT services.

🛠 Option 1: Use Port-Forwarding (Recommended)

If the dependent services are deployed in a Kubernetes cluster, you can use kubectl port-forward to access them locally:

kubectl port-forward -n egov {egov-idgen} 8087:8080
kubectl port-forward -n egov {egov-mdms} 8088:8080
kubectl port-forward -n egov {egov-user} 8089:8080
kubectl port-forward -n egov {egov-workflow-v2} 8090:8080
kubectl port-forward -n egov {egov-localisation} 8091:8080
kubectl port-forward -n egov {egov-url-shortner} 8092:8080
kubectl port-forward -n egov {egov-hrms} 8093:8080

Note: Replace {egov-<service>} with the actual pod name in your cluster for each service.

This is the most preferred way to run services locally without deploying all DIGIT services yourself.

Option 2: Run All Dependent Services Locally

If you don’t have access to a DIGIT environment, you can clone and run each dependent service locally. You will need to:

• Pull the repositories

• Configure local PostgreSQL and Kafka

• Set the correct ports and DB connections in each service’s application.properties

• Start each service

Recommended Machine Specifications

Running all dependent services locally is resource-intensive. Below are the minimum and recommended machine specifications based on community best practices and real-world experience:

Specification	Minimum	Recommended
CPU	4 cores	8+ cores
RAM	16 GB	32 GB or more
Disk Space	50 GB free (SSD)	100+ GB (SSD preferred)
OS	Ubuntu 20.04+ / macOS / Windows 10+ (WSL2 for Linux compatibility)	Ubuntu 22.04 LTS or macOS
Java	OpenJDK 17+	OpenJDK 17
Network	Stable internet connection (for dependency downloads, npm, maven, etc.)	Required
Others	Node.js (for UI), Maven 3.8+, PostgreSQL, Kafka, Elasticsearch	Same

💡 Note: Running heavy services like Kafka, Elasticsearch, PostgreSQL, and multiple Spring Boot apps simultaneously can easily consume 80–90% of system resources on a 16 GB RAM machine. A machine with 32 GB RAM and SSD storage is highly recommended for a smooth experience.

4

Configure application.properties

Edit your local application.properties or application-local.properties file with the appropriate values:

spring.datasource.url=jdbc:postgresql://localhost:5432/{your_local_db_name}
spring.flyway.url=jdbc:postgresql://localhost:5432/{your_local_db_name}
egov.mdms.host=http://localhost:8088
egov.user.host=http://localhost:8089
egov.idgen.host=http://localhost:8087
egov.localization.host=http://localhost:8091
egov.hrms.host=http://localhost:8093
egov.url.shortner.host=http://localhost:8092
egov.workflow.host=http://localhost:8090

👉 Replace {your_local_db_name} with your actual PostgreSQL database name and ensure the credentials are correctly set.

5

Prepare the PostgreSQL Database

• Create the PostgreSQL database and user (if not already done).

• On service startup, Flyway will apply migrations.

• Ensure the database is accessible and the credentials are correct.

6

Build and run ccrs-services

Build and start the service using Maven:

mvn clean install
java -jar target/*.jar --spring.profiles.active=local

7

Verify the Setup

• The service should connect to your local PostgreSQL instance.

• It should also be able to reach all dependent services via port-forwarded URLs.

• Check application logs to confirm successful startup.

Notes

• All key configurations are controlled through the application.properties file.

• If you're using local PostgreSQL and running services locally, ensure your Kafka, Postgres, and all ports are correctly mapped.

• You may need to run egov-persister locally or ensure it’s port-forwarded to persist data.