> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/complaints-management/deploy/setup/single-machine-setup.md).

# Single Machine Setup

Deploy DIGIT CMS on a single machine

## Overview

This guide helps you run the full DIGIT Complaint Management System (CMS) — including all core DIGIT services, the citizen and employee web apps, and the tools for setting up a city and loading its data.

Three ways to run it, from a laptop container stack to a full deployment. Pick one and follow it from start to finish.

## Choose Your Setup Path

There are three ways to run this stack. Pick the one that fits what you're doing:

<table><thead><tr><th width="172.82421875">Path</th><th width="335.86328125">Best for</th><th>What you need</th></tr></thead><tbody><tr><td><a href="/complaints-management/deploy/setup/single-machine-setup/docker-compose.md"><strong>Option A: Docker Compose</strong></a></td><td>Quick setup, no extra tools. For developers who want to try things out quickly.</td><td>Docker only</td></tr><tr><td><a href="/complaints-management/deploy/setup/single-machine-setup/tilt.md"><strong>Option B: Tilt</strong></a></td><td>Dashboard, grouped services, dev buttons. For developers who want to change code and experiment.</td><td>Docker + Tilt</td></tr><tr><td><a href="/complaints-management/deploy/setup/single-machine-setup/ansible.md"><strong>Option C: Ansible</strong></a></td><td>A real deployment — web server, secret store, monitoring, onboarding wizard. A laptop or a server.</td><td>Ansible (a script installs it)</td></tr></tbody></table>

**Key differences:**

* **Options A and B** run on your machine using local ports (`localhost:18xxx`) — no web server involved.
* **Option C** is a real deployment: one command builds and serves the whole stack on standard web ports, either on your machine or a server. It's also the only option with the browser-based onboarding wizard.

**Not sure?** Want to poke at the API or change some code — [**Option A.**](/complaints-management/deploy/setup/single-machine-setup/docker-compose.md)&#x20;

Setting the system up for someone to actually use — [**Option C**.](/complaints-management/deploy/setup/single-machine-setup/ansible.md)

{% hint style="info" %}
**On Windows?** Use [WINDOWS-QUICKSTART](/complaints-management/deploy/setup/single-machine-setup/windows-quickstart.md)  — the full stack runs locally via WSL2 and has been tested end-to-end on a 16 GB machine.

**On macOS?** Use [MAC-QUICKSTART](/complaints-management/deploy/setup/single-machine-setup/macos-quickstart.md) (validated end-to-end on a 16 GB machine; the playbook self-heals the WSL-specific quirks).&#x20;
{% endhint %}

## Pre-requisites

{% hint style="info" %}
**Going straight to Option C?** Skip this section. Its prerequisites are different (Ansible, Node, Python — not Docker, which the playbook installs for you) and [a script installs them](https://github.com/egovernments/Citizen-Complaint-Resolution-System/tree/master/local-setup#step-2--install-the-prerequisites).
{% endhint %}

See below for Options A and B:

#### Required

| Tool                                                       | Version | Install Link                                                                                                                                                                                | What it's for                      |
| ---------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| [Docker Desktop](https://docs.docker.com/get-docker/)      | 24+     | [Mac](https://docs.docker.com/desktop/install/mac-install/) / [Windows](https://docs.docker.com/desktop/install/windows-install/) / [Linux](https://docs.docker.com/desktop/install/linux/) | Runs all services as containers    |
| [Docker Compose](https://docs.docker.com/compose/install/) | v2+     | Included with Docker Desktop                                                                                                                                                                | Orchestrates multi-container setup |
| [Git](https://git-scm.com/downloads)                       | 2.x     | [Download](https://git-scm.com/downloads)                                                                                                                                                   | Clone the repository               |

{% hint style="info" %}
**Memory**: Allocate at least **8 GB RAM** to Docker. The stack runs in \~3.8 GB but needs headroom. In Docker Desktop: Settings > Resources > Memory > 8 GB.
{% endhint %}

#### Optional

| Tool                                                | Install Link                                                                                                                                | When you need it                                          |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [Tilt](https://docs.tilt.dev/install.html)          | [See Tilt install section](https://github.com/egovernments/Citizen-Complaint-Resolution-System/tree/master/local-setup#step-1-install-tilt) | Only if using Option B                                    |
| [Node.js 20+](https://nodejs.org/en/download/)      | [Download](https://nodejs.org/)                                                                                                             | Running Postman tests with Newman (`npx`)                 |
| [Python 3.8+](https://www.python.org/downloads/)    | [Download](https://www.python.org/downloads/)                                                                                               | Running the CI dataloader script                          |
| **JDK 17 or 21**                                    | [Temurin 17](https://adoptium.net/temurin/releases/?version=17)                                                                             | Hot reload for PGR Java code (Tilt only) — see note below |
| [Maven 3.9+](https://maven.apache.org/download.cgi) | [Download](https://maven.apache.org/download.cgi)                                                                                           | Hot reload for PGR Java code (Tilt only)                  |
| [Yarn](https://yarnpkg.com/getting-started/install) | [Download](https://yarnpkg.com/)                                                                                                            | Hot reload for DIGIT UI (Tilt only)                       |

{% hint style="info" %}
**JDK version matters**

⚠️ **Use JDK 17 or 21 — not 23 or 25.**

`backend/pgr-services` is built to target Java 17, and it only builds successfully on JDK 17 or 21.

**If you use JDK 23 or 25, the build will fail** — but in a confusing way. Here's why: the version of Lombok this project uses (inherited from Spring Boot) doesn't work with the newer JDKs' compiler internals. This causes `@Builder`-generated code to silently not get created, so you'll see dozens of errors like `cannot find symbol: method builder()`.

💡 **Important:** the error message never mentions Lombok or your JDK version — so it's easy to mistake this for broken source code, when the real issue is just your JDK version.

**How to Check and Fix This**

Ubuntu's default JDK package may install a version newer than 21. To check which JDK is actually being used:

```bash
mvn -version
```

⚠️ Check `mvn -version`, not `java -version` — Maven can be using a different JDK than your terminal's default.

**If it shows the wrong version**, switch it with:

```bash
sudo update-alternatives --config java
```

{% endhint %}

## Reference

Ports, memory budgets, what each service does, API/database access, Postman collections, and troubleshooting now live in **`docs/STACK-REFERENCE.md`** — this page stays focused on the setup walkthrough.

<table><thead><tr><th width="451.52734375">Looking for</th><th>Go to</th></tr></thead><tbody><tr><td>Every service, port and memory limit</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md#whats-included">STACK-REFERENCE.md</a></td></tr><tr><td>Calling the API by hand</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md#api-access">STACK-REFERENCE.md</a></td></tr><tr><td>Connecting to the database</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md#database-access">STACK-REFERENCE.md</a></td></tr><tr><td>Running the Postman collections</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md#running-postman-api-tests">STACK-REFERENCE.md</a></td></tr><tr><td>Loading master data from a script</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md#loading-master-data-from-a-script">STACK-REFERENCE.md</a></td></tr><tr><td>Troubleshooting a Compose or Tilt stack</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md#troubleshooting">STACK-REFERENCE.md</a></td></tr><tr><td>Repository layout</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md#project-structure">STACK-REFERENCE.md</a></td></tr><tr><td>Everything the Ansible playbook does</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/ansible/README.md">ansible/README.md</a></td></tr><tr><td>Running the stack in production</td><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/docs/operations/README.md">operations handbook</a></td></tr></tbody></table>

## Related Setup Docs

<table><thead><tr><th width="247.16015625">Guide</th><th>What it covers</th></tr></thead><tbody><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/ONBOARDING-AND-ADDONS.md">ONBOARDING-AND-ADDONS.md</a></td><td>Create a city and load its data; turn on notifications, the dashboard and the other add-ons</td></tr><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/STACK-REFERENCE.md">STACK-REFERENCE.md</a></td><td>Ports, memory, API and database access, Postman, troubleshooting</td></tr><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/LOCALHOST-FULL-AND-SLIM.md">LOCALHOST-FULL-AND-SLIM.md</a></td><td>Two ready-made presets for deploying Option C to this machine</td></tr><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/LOCAL-SETUP-GUIDE.md">LOCAL-SETUP-GUIDE.md</a></td><td>Running the Compose stack on a machine with about 4 GB of RAM</td></tr><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/HYBRID-SETUP.md">HYBRID-SETUP.md</a></td><td>Some services local, the rest on a shared server</td></tr><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/REMOTE-DEV-SETUP.md">REMOTE-DEV-SETUP.md</a></td><td>Developing against a remote stack</td></tr><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/HOT-DEPLOY-GUIDE.md">HOT-DEPLOY-GUIDE.md</a></td><td>Pushing a code change into a running stack without a full redeploy</td></tr><tr><td><a href="https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/local-setup/docs/SERVICE-STARTUP-SEQUENCE.md">SERVICE-STARTUP-SEQUENCE.md</a></td><td>The order services come up in, and what waits on what</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digit.org/complaints-management/deploy/setup/single-machine-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.