docs: add Docker Desktop on macOS solution#115
docs: add Docker Desktop on macOS solution#115pablodeymo wants to merge 1 commit intoblockblaz:mainfrom
Conversation
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
| 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. |
| 2. Go to **Resources** → **Network** | ||
| 3. Enable **"Enable host networking"** | ||
| 4. Click **Apply & Restart** | ||
|
|
There was a problem hiding this comment.
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."
| 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. |
This PR adds a toubleshooting item for network configuration in MacOS to display correctly Grafana metrics.