Skip to content

docs: add Docker Desktop on macOS solution #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pablodeymo wants to merge 2 commits into
base: main
Choose a base branch
from
+15 −0
Open

docs: add Docker Desktop on macOS solution #115

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2ed793a
docs: add Docker Desktop on macOS solution
MegaRedHand Feb 13, 2026
22e5031
Merge branch 'main' into document-docker-desktop-on-mac-problem
pablodeymo Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -531,6 +531,21 @@ NETWORK_DIR=local-devnet ./spin-node.sh --node all --generateGenesis --forceKeyG
./generate-genesis.sh local-devnet/genesis --forceKeyGen
```

---

**Problem**: Grafana dashboards show "No data"

On macOS, this is typically caused by Docker's **host network mode** (`--network host`) not working out of the box. lean-quickstart uses host networking so Prometheus can scrape node metrics endpoints on `localhost`. Without host networking enabled in Docker Desktop, Prometheus cannot reach the node metrics ports, resulting in empty dashboards.
Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The explanation states that "lean-quickstart uses host networking so Prometheus can scrape node metrics endpoints on localhost", but this is not quite accurate. Looking at the Prometheus configuration generation in generate-prometheus-config.sh (line 50), Prometheus actually scrapes using host.docker.internal:${port}, not localhost:${port}. The Prometheus container is configured with extra_hosts: - "host.docker.internal:host-gateway" to resolve this hostname. Consider revising the explanation to be more precise about the networking mechanism.

Suggested change
On macOS, this is typically caused by Docker's **host network mode** (`--network host`) not working out of the box. lean-quickstart uses host networking so Prometheus can scrape node metrics endpoints on `localhost`. Without host networking enabled in Docker Desktop, Prometheus cannot reach the node metrics ports, resulting in empty dashboards.
On macOS, this is typically caused by Docker's **host network mode** (`--network host`) not working out of the box. In lean-quickstart, Prometheus runs in a container and scrapes node metrics endpoints on the host via `host.docker.internal:${port}` (with `extra_hosts: "host.docker.internal:host-gateway"` used to resolve this hostname to the host). If host networking / host-gateway resolution is not working in Docker Desktop, Prometheus cannot reach the node metrics ports, resulting in empty dashboards.

Copilot uses AI. Check for mistakes.

**Solution**: Enable the "Enable host networking" option in Docker Desktop:

1. Open **Docker Desktop** → **Settings** (gear icon)
2. Go to **Resources** → **Network**
3. Enable **"Enable host networking"**
4. Click **Apply & Restart**

Copy link

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After enabling host networking in Docker Desktop and clicking "Apply & Restart", users will need to restart their devnet containers for the changes to take effect. Consider adding a note about restarting the devnet after making this Docker Desktop configuration change, for example: "After enabling this setting and restarting Docker Desktop, restart your devnet with spin-node.sh for the changes to take effect."

Suggested change
After Docker Desktop finishes restarting, restart your devnet with `spin-node.sh` (for example, `NETWORK_DIR=local-devnet ./spin-node.sh --node all`) so the new host networking setting is applied to your containers.

Copilot uses AI. Check for mistakes.
For more details, see the [Docker Desktop host networking documentation](https://docs.docker.com/engine/network/drivers/host/#docker-desktop).

## Automation Features

This quickstart includes automated configuration parsing:
Expand Down