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@22Steps
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.
Log In
Open in your browser:
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:
Build it:
git clone https://github.com/egovernments/digit-configurator && npm ci && npm run buildCopy the build output into
~/digit/configurator/Set
nginx_features.configurator: truein your configRe-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
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?