> 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/cms-v2.11/deploy/setup/single-machine-setup/macos-quickstart.md).

# macOS Quickstart

DIGIT in one terminal session

## Overview

*Last tested: May 20, 2026, on an Apple Silicon Mac with OrbStack.*

This guide gets the full DIGIT stack (\~36 containers) running with a single command: `./deploy.sh <tenant>`. No admin password needed, no virtual machine to set up, no extra repos, nothing to run afterwards.

## Pre-requisites&#x20;

Make sure you have:

* **Apple Silicon Mac** with at least **16 GB RAM** allocated to Docker, and **30 GB free disk space** (OrbStack grows its virtual disk as needed).
* **OrbStack** installed (recommended) — or Docker Desktop with Rosetta enabled in *Settings → General*.

**Install everything you need:**

```
# 1. Docker runtime (pick one — OrbStack is the validated path)
brew install --cask orbstack && orb start
# (or: install Docker Desktop and enable Rosetta in Settings → General)

# 2. Ansible (the deploy runner)
brew install ansible

# 3. Tools used by the deploy
brew install git python@3.12 node@22
```

## Steps

{% stepper %}
{% step %}

### Clone the Repo and Configure

The defaults work as-is — you can edit `maputo.yml` later if you want, but nothing needs changing to get started.

```
git clone https://github.com/ChakshuGautam/Citizen-Complaint-Resolution-System.git ccrs
cd ccrs/local-setup/ansible

cp inventory/host_vars/maputo.yml.example inventory/host_vars/maputo.yml
# Edit maputo.yml if you want — defaults are validated.

./deploy.sh maputo
```

{% endstep %}

{% step %}

### Deploy

```bash
./deploy.sh maputo
```

This one command does everything: sets up config files, pulls container images, brings up \~36 containers, and checks that everything's healthy. You don't need to run anything else afterward.

**How long this takes:**

* First time ever (with image downloads): a few extra minutes on top of the below.
* First full setup on an empty system: **\~3 minutes**.
* Re-running later on an already-working setup: **\~30 seconds**.

**Watch it live**, in a second terminal:

```bash
tail -f /tmp/mac-stack-up.progress
```

Look for the message `mac-stack-up: CONVERGED on attempt N/10` — that means it succeeded.

💡 **If you see `mac-stack-up: ABORT — LEAKED NETWORK ENDPOINT`:** stop the deploy, run `docker ps -aq | xargs -r docker rm -f`, restart OrbStack/Docker, then run `./deploy.sh maputo` again.
{% endstep %}

{% step %}

### Verify It Worked

Run these checks — each should return `200`:

```bash
curl -sS -o /dev/null -w 'mdms:    %{http_code}\n' http://localhost/egov-mdms-service/health
curl -sS -o /dev/null -w 'ui:      %{http_code}\n' http://localhost/digit-ui/
curl -sS -o /dev/null -w 'status:  %{http_code}\n' http://localhost/status/
```

And confirm login works:

```bash
curl -sS http://localhost/user/oauth/token \
  -H 'Authorization: Basic ZWdvdi11c2VyLWNsaWVudDo=' \
  -d 'username=ADMIN&password=eGov@123&tenantId=pg&userType=EMPLOYEE&scope=read&grant_type=password' \
  | python3 -c 'import json,sys;print("auth:    "+json.load(sys.stdin).get("access_token","MISSING")[:24]+"...")'
```

This should print a real token, not "MISSING.
{% endstep %}

{% step %}

### Log In

Open in your browser:

| What                        | URL                                                                  |
| --------------------------- | -------------------------------------------------------------------- |
| Employee & citizen app      | `http://localhost/digit-ui/`                                         |
| Health dashboard (Gatus)    | `http://localhost/status/`                                           |
| Configurator (DIGIT Studio) | `http://localhost/configurator/` *(see note below — off by default)* |

**Login:** `ADMIN` / `eGov@123`, tenant `pg`

**Want the Configurator too?** It's disabled by default. To turn it on:

1. Build it: `git clone https://github.com/egovernments/digit-configurator && npm ci && npm run build`
2. Copy the build output into `~/digit/configurator/`
3. Set `nginx_features.configurator: true` in your config
4. Re-run `./deploy.sh maputo`
   {% endstep %}
   {% endstepper %}

#### What's Not Included in This Setup

* **Creating a new tenant** (like a fresh city other than `pg`) — this needs a feature called MCP tenant onboarding, which isn't yet supported on Mac (the required image doesn't support Mac's chip architecture yet). This is disabled by default (`enable_mcp: false`) until that's fixed.
* **Notifications (SMS/WhatsApp via Novu/Twilio)** — disabled by default (`enable_novu: false`). Turn this on only once you actually need to send messages.

***

#### Stop and Restart

**To stop without losing data:**

```bash
docker compose -f ~/digit/docker-compose.egov-digit.yaml -f ~/digit/docker-compose.fast-path.yml down
```

**To bring it back up:**

```bash
docker compose -f ~/digit/docker-compose.egov-digit.yaml -f ~/digit/docker-compose.fast-path.yml up -d
```

**Or just re-run the deploy script** — it's safe to run again and takes about 30 seconds on an already-working setup:

```bash
cd ccrs/local-setup/ansible && ./deploy.sh maputo
```

#### Troubleshooting

| Problem                                                          | What it means                                                                         | What to do                                                                                |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `ansible-playbook not found`                                     | Ansible wasn't installed correctly                                                    | Run `brew install ansible` — don't use `pip3 install --user`                              |
| `Permission denied: /opt/digit-ui-esbuild`                       | A config setting is wrong                                                             | Make sure you haven't manually changed `digit_ui_mode` — Mac always uses `container` mode |
| JVM containers keep crashing with a `KeyManagementService` error | You set a tenant that doesn't exist yet                                               | Switch `state_root` back to `pg`                                                          |
| `mac-stack-up: ABORT — LEAKED NETWORK ENDPOINT`                  | Leftover containers from a previous run                                               | Stop the deploy, run `docker ps -aq \| xargs -r docker rm -f`, restart Docker, try again  |
| Stuck at `attempt N/10 ... 0/0 up-or-healthy`                    | Usually a container image mismatch (e.g., MCP enabled on the wrong chip architecture) | Check the log file `/tmp/mac-stack-up.<N>.log` for details                                |


---

# 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/cms-v2.11/deploy/setup/single-machine-setup/macos-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.