Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

1

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.

2

Deploy

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:

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.

3

Verify It Worked

Run these checks — each should return 200:

And confirm login works:

This should print a real token, not "MISSING.

4

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

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:

To bring it back up:

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

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

Was this helpful?