Skip to content

docs: add Docker Desktop on macOS solution#115

Open
pablodeymo wants to merge 1 commit intoblockblaz:mainfrom
lambdaclass:document-docker-desktop-on-mac-problem
Open

docs: add Docker Desktop on macOS solution#115
pablodeymo wants to merge 1 commit intoblockblaz:mainfrom
lambdaclass:document-docker-desktop-on-mac-problem

Conversation

@pablodeymo
Copy link

@pablodeymo pablodeymo commented Feb 13, 2026

This PR adds a toubleshooting item for network configuration in MacOS to display correctly Grafana metrics.

Copilot AI review requested due to automatic review settings February 13, 2026 19:12
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR adds troubleshooting documentation for a macOS-specific issue where Grafana dashboards show "No data" when running the devnet. The solution involves enabling Docker Desktop's "Enable host networking" feature, which allows the --network host flag to work properly on macOS, enabling Prometheus to scrape metrics from node containers.

Changes:

  • Added a new troubleshooting entry documenting the "Grafana dashboards show No data" problem specific to macOS users
  • Provided step-by-step instructions to enable host networking in Docker Desktop settings
  • Included a reference link to Docker's official documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.


**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.
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants