> 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/windows-quickstart.md).

# Windows Quickstart

Windows Quickstart — DIGIT via WSL2 in one session

## Overview

This guide gets the full DIGIT stack running with a single command: `./deploy.sh <name>`. The setup script automatically handles WSL2-specific quirks — memory limits, mount issues, Node.js setup — so you shouldn't need to troubleshoot those yourself.

**Using Linux instead of Windows?** These same steps work on any Linux machine or VM. Only the WSL2-specific parts are Windows-only.

**What You'll Get**

Running the setup gives you about 40 containers, covering:

* All core DIGIT services
* The complaints management module (CMS)
* Employee UI and citizen-facing app
* DIGIT Studio (the configurator)
* Kong (API gateway) and nginx (running on port 80)
* A health status dashboard (Gatus)
* Monitoring tools: Grafana, Prometheus, Loki, and Tempo
* OpenBao (secrets management)

Everything comes pre-loaded with sample data on two test tenants (`pg` and `pg.citya`) — so you can log in and start exploring right away, no extra setup needed.

Two sizing profiles (see step 4):

<table><thead><tr><th width="207.84375">Template</th><th width="205.08984375">Fits</th><th>Difference</th></tr></thead><tbody><tr><td><code>localhost-slim.yml.example</code></td><td><strong>16 GB machine</strong> (12 GB WSL VM)</td><td>No Novu notifications stack (~2 GB). Everything else identical.</td></tr><tr><td><code>localhost-full.yml.example</code></td><td>32 GB machine</td><td>Adds Novu (SMS/WhatsApp delivery pipeline).</td></tr></tbody></table>

### Pre-requisites

* **Windows 10 or 11** with hardware virtualisation turned on (Intel VT-x or AMD SVM). This is usually on by default. If Step 1 fails with an error `0x80370102`, turn it on manually in your BIOS.
* **At least 16 GB of RAM** and **\~60 GB of free disk space**.
* **No Docker Desktop.** If it's already installed, either uninstall it or turn off its WSL integration for this distro. The setup script installs its own Docker Engine in WSL — running Docker Desktop at the same time causes conflicts.

## Steps

{% stepper %}
{% step %}

### Install WSL2 + Ubuntu&#x20;

Open **PowerShell as Administrator** and run:

```
wsl --update
wsl --install -d Ubuntu-24.04
```

* Reboot if Windows asks you to.
* If the distro doesn't show up right away, just run the install command again.
* On first launch, create your Linux username and password.

```
uname -a          # must contain "microsoft ... WSL2"
systemctl is-system-running   # "running" or "degraded" (Ubuntu 24.04 default)
```

**If systemd shows "offline" instead:** Add this to `/etc/wsl.conf`:

```
[boot]
systemd=true
```

Then, from PowerShell, run `wsl --shutdown` and reopen Ubuntu.
{% endstep %}

{% step %}

### Install the deploy tools inside WSL

Install the deploy tools inside WSL.&#x20;

```
ansible --version    # ansible-core must be < 2.19 — Ubuntu 24.04's apt (2.16.x) is correct
```

> **Version matters.** you need `ansible-core` below version 2.19. Ubuntu 24.04's default package (2.16.x) is correct — don't `pip install` a newer version.
> {% endstep %}

{% step %}

### Clone the repo inside WSL

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

> **Never run the stack from a Windows-side clone** Clone this inside your Linux home folder — never from a Windows path like `/mnt/c/...`. Cloning from Windows breaks shell scripts (due to line-ending differences) and is much slower.
> {% endstep %}

{% step %}

### Set up your configuration file

```
cd local-setup/ansible
cp inventory/host_vars/localhost-slim.yml.example inventory/host_vars/mybox.yml
# 32 GB machine? use localhost-full.yml.example instead
```

*(Have a 32 GB machine instead of 16 GB? Use `localhost-full.yml.example` instead.)*

The defaults work as-is — you don't need to edit anything for a local setup. `mybox` is just a name you're picking for this deployment; you'll reuse it in the next step.
{% endstep %}

{% step %}

### Deploy

Switch to root, then run the deploy script:

```
sudo -i
cd /home/<you>/Citizen-Complaint-Resolution-System/local-setup/ansible
./deploy.sh mybox
```

*(Root access is required because this installs Docker and writes system-level config.)*

**Heads up — this will stop once, on purpose, the first time.** The script adjusts WSL's memory limits (setting your Windows `.wslconfig` to 12 GB RAM / 16 GB swap / 6 CPUs by default) and then stops, because it can't restart the WSL machine it's running inside. When that happens:

1. From PowerShell, run:

```
wsl --shutdown        # from PowerShell
```

* Reopen Ubuntu.
* Run the same command again:

```
/deploy.sh mybox
```

* From here, it runs on its own through: installing Docker, fixing WSL mount settings, pulling container images (this is the slowest part — tens of GB), installing Node 20, building the UI, starting around 40 containers, and running health checks.

  **To watch progress live**, open a second WSL terminal and run:

```
tail -f /opt/digit/digit-stack-up.mybox.progress
```

**How long this takes:**

* First time on a fresh machine: **30–60 minutes**, depending on your internet speed.
* Re-running it later on an already-working setup: **1–2 minutes**.
  {% endstep %}

{% step %}

### Verify and log in&#x20;

Open these in your Windows browser:

<table><thead><tr><th width="254.97265625">What</th><th>URL</th></tr></thead><tbody><tr><td>Employee UI</td><td><a href="http://localhost/digit-ui/">http://localhost/digit-ui/</a> — <code>ADMIN</code> / <code>eGov@123</code>, select <strong>City A</strong></td></tr><tr><td>Citizen SPA</td><td><a href="http://localhost/citizen/">http://localhost/citizen/</a></td></tr><tr><td>Configurator (DIGIT Studio)</td><td><a href="http://localhost/configurator/">http://localhost/configurator/</a></td></tr><tr><td>Health dashboard (Gatus)</td><td><a href="http://localhost/status/">http://localhost/status/</a></td></tr><tr><td>Grafana</td><td><a href="http://localhost:13000/">http://localhost:13000</a></td></tr></tbody></table>

Before opening a browser, double-check the script's final **"INFRA VALIDATION RESULTS"** summary — every row there should be green.
{% endstep %}
{% endstepper %}

#### Day-to-Day Use

Once everything's set up, bringing the stack back up (after a reboot or `wsl --shutdown`) just takes the same command again:

```bash
sudo -i
cd .../local-setup/ansible
./deploy.sh mybox
```

**Good to know:**

* Your data is saved in Docker volumes, so nothing is lost between restarts.
* The stack itself lives in `/opt/digit`.
* Keep `/opt/digit/.openbao/init.json` safe — it's needed to unlock the secrets store on future deploys.

#### Troubleshooting

<table><thead><tr><th width="341.88671875">Symptom</th><th>Cause / fix</th></tr></thead><tbody><tr><td><code>x509: certificate has expired</code> on image pull</td><td><code>registry.preview.egov.theflywheel.in</code>'s cert lapsed. The templates ship an <code>insecure_registries</code> workaround already; if you removed it, put it back or get the cert renewed.</td></tr><tr><td><code>cannot execute: required file not found</code> / <code>$'\r'</code> errors</td><td>You're in a Windows-side clone. Re-clone inside WSL (step 3).</td></tr><tr><td><code>Permission denied: inventory/hosts.yml</code></td><td>Run <code>deploy.sh</code> as root (step 5).</td></tr><tr><td>Deploy frozen AND new WSL windows won't open</td><td>VM memory starvation — the <code>.wslconfig</code> caps aren't applied. <code>wsl --shutdown</code> from PowerShell, reopen, re-run the deploy (it verifies the caps before doing anything heavy).</td></tr><tr><td><code>path / is mounted on / but it is not a shared or slave mount</code></td><td>Handled automatically (<code>make-rshared-root.service</code>) — seeing it means you're on a branch without the fix.</td></tr><tr><td>Containers OOM-killed / restart-looping</td><td><code>free -h</code> inside WSL; check <code>dmesg | grep -i oom</code>. On 16 GB machines use the <strong>slim</strong> template and close heavy Windows apps.</td></tr><tr><td>Port 80 already in use</td><td>Something on Windows (IIS?) owns it: <code>netstat -ano | findstr :80</code> in PowerShell.</td></tr><tr><td><code>Conditional result was ...</code> errors at play start</td><td>ansible-core ≥ 2.19 — install the apt version (step 2).</td></tr></tbody></table>

#### What's Not Included (Slim Setup)

The one thing missing from this slim setup is **Novu notifications** — this is what sends SMS and WhatsApp messages.

Everything else is included, including the tenant-onboarding wizard (MCP) in the configurator.

**Want Novu too?** You'll need about 2 GB more free memory. On a bigger machine, use `localhost-full.yml.example` instead of the slim profile.


---

# 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/windows-quickstart.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.