From 0414f3b981466c57fd7f2cdefc303eaff86adc5f Mon Sep 17 00:00:00 2001 From: johnnymatthews <9611008+johnnymatthews@users.noreply.github.com> Date: Wed, 19 Aug 2026 16:17:39 +0100 Subject: [PATCH 1/2] Clears up exposing port 8080 confusion. Closes #415. --- .../run/operations/troubleshooting/index.md | 18 +++++++++++++++ content/run/run-a-host/install/index.md | 2 +- content/run/run-a-host/quickstart/index.md | 22 +++++++++++++++++++ content/run/run-a-host/register/index.md | 2 +- 4 files changed, 42 insertions(+), 2 deletions(-) diff --git a/content/run/operations/troubleshooting/index.md b/content/run/operations/troubleshooting/index.md index 4bdfead..0a29ab5 100644 --- a/content/run/operations/troubleshooting/index.md +++ b/content/run/operations/troubleshooting/index.md @@ -182,6 +182,24 @@ The Host client is running but can't sync from a Generator client. Check `docker See [Install](/run/run-a-host/install/#use-docker) for how to confirm a healthy connection. +### My Host appears offline in the dashboard but is still running + +The dashboard decides online/offline by probing `http://:8080/health`, using the IP it reads from your registered connection string (the `/ip4//...` part of your libp2p multiaddr). If port `8080` isn't reachable from the internet, the probe fails and your Host shows as offline even though `docker ps` reports the container as healthy and the node is up and working normally. + +This is the most common reason a running Host appears offline, and it almost always comes down to `8080` not being published or opened: + +- **Docker:** the default `docker run` in [Install](/run/run-a-host/install/) does not publish `8080`. Add `-p 8080:8080` to that command and to your persistent-host command or Compose file. +- **Firewall / security group:** open inbound TCP `8080` on your server's firewall or cloud security group (Hetzner, DigitalOcean, GCP, AWS, etc.). This is separate from the P2P port `9171`. The dashboard online check only looks at `8080`. +- **Reverse proxy:** if you put nginx in front (as in the [Quickstart](/run/run-a-host/quickstart/)), make sure it routes `/health` to the Host's health server on port `8080`, not to DefraDB on `9181`. Otherwise the probe reaches DefraDB, which doesn't answer `/health` the way the dashboard expects. + +Confirm the fix by running the same probe the dashboard runs, from outside your server: + +```shell +curl -s http://:8080/health | jq -r '.status' +``` + +A healthy Host returns `healthy`. A connection refused or timeout means `8080` still isn't reachable from outside. The endpoint returns `"unhealthy"` (HTTP 503) only while the Host's DefraDB node or processing pipeline is still initializing. That clears once startup finishes. + ## Viewkit ### image not found / library not loaded: libwasmer.dylib diff --git a/content/run/run-a-host/install/index.md b/content/run/run-a-host/install/index.md index e495d51..80166f3 100644 --- a/content/run/run-a-host/install/index.md +++ b/content/run/run-a-host/install/index.md @@ -69,7 +69,7 @@ Pull the image and start it with a single `docker run`. You supply two values: a | `9181` | DefraDB GraphQL + REST API | | | `9182` | GraphQL Playground UI | | | `9171` | libp2p P2P networking | Must be reachable from the internet — open/forward this port | - | `8080` | Health + metrics | Served inside the container; publish with `-p 8080:8080` if you want to scrape it | + | `8080` | Health + metrics | Served inside the container. Publish with `-p 8080:8080` and open it in your firewall so the public Hosts dashboard can probe `/health` and show your Host as online. The default `docker run` above does not publish it. | 1. Confirm the container is up: diff --git a/content/run/run-a-host/quickstart/index.md b/content/run/run-a-host/quickstart/index.md index 91d81fa..5a90a31 100644 --- a/content/run/run-a-host/quickstart/index.md +++ b/content/run/run-a-host/quickstart/index.md @@ -229,6 +229,28 @@ http { proxy_set_header Host $host; } + location = /health { + if ($request_method = OPTIONS) { return 204; } + proxy_pass http://shinzo-host:8080/health; + proxy_set_header Host $host; + } + + location = /registration { + if ($request_method = OPTIONS) { return 204; } + proxy_pass http://shinzo-host:8080/registration; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + } + + location = /registration-app { + if ($request_method = OPTIONS) { return 204; } + proxy_pass http://shinzo-host:8080/registration-app; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + } + location = /api/v0/graphql { if ($request_method = OPTIONS) { return 204; } proxy_pass http://shinzo-host:9181/api/v0/graphql; diff --git a/content/run/run-a-host/register/index.md b/content/run/run-a-host/register/index.md index 035c2dc..ad6ca20 100644 --- a/content/run/run-a-host/register/index.md +++ b/content/run/run-a-host/register/index.md @@ -7,7 +7,7 @@ To participate in the Shinzo Network and make your view publically available, yo ## Register with the GUI -1. Start your Host with the health/registration port published (`-p 8080:8080`). The registration app is served on port `8080`, and the default command in [Install](/run/run-a-host/install/) does not publish it. +1. Start your Host with the health/registration port published (`-p 8080:8080`) and open inbound TCP `8080` in your firewall. The registration app is served on port `8080`, and the public Hosts dashboard also probes `http://:8080/health` to decide whether your Host shows as online. If `8080` isn't reachable from the internet, your Host shows as offline even while it's running fine. The default command in [Install](/run/run-a-host/install/) does not publish it. 1. Add the Shinzo Testnet to your browser wallet with the following values: - Network name: `Shinzo` - Default RPC URL: `http://testnet.shinzo.network:8545` From f6e9bd218b45c4049d5157fe1a722d0d6c3619b3 Mon Sep 17 00:00:00 2001 From: Johnny <9611008+johnnymatthews@users.noreply.github.com> Date: Thu, 20 Aug 2026 09:59:33 +0100 Subject: [PATCH 2/2] Just a couple of copy cleanups. Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- content/run/operations/troubleshooting/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/run/operations/troubleshooting/index.md b/content/run/operations/troubleshooting/index.md index 0a29ab5..1bb9448 100644 --- a/content/run/operations/troubleshooting/index.md +++ b/content/run/operations/troubleshooting/index.md @@ -184,13 +184,13 @@ See [Install](/run/run-a-host/install/#use-docker) for how to confirm a healthy ### My Host appears offline in the dashboard but is still running -The dashboard decides online/offline by probing `http://:8080/health`, using the IP it reads from your registered connection string (the `/ip4//...` part of your libp2p multiaddr). If port `8080` isn't reachable from the internet, the probe fails and your Host shows as offline even though `docker ps` reports the container as healthy and the node is up and working normally. +The dashboard determines if a node is online/offline by probing `http://:8080/health`, using the IP it reads from your registered connection string (the `/ip4//...` part of your libp2p multiaddr). If port `8080` isn't reachable from the internet, the probe fails and your Host client shows as offline even though `docker ps` reports the container as healthy and the node is up and working normally. This is the most common reason a running Host appears offline, and it almost always comes down to `8080` not being published or opened: - **Docker:** the default `docker run` in [Install](/run/run-a-host/install/) does not publish `8080`. Add `-p 8080:8080` to that command and to your persistent-host command or Compose file. - **Firewall / security group:** open inbound TCP `8080` on your server's firewall or cloud security group (Hetzner, DigitalOcean, GCP, AWS, etc.). This is separate from the P2P port `9171`. The dashboard online check only looks at `8080`. -- **Reverse proxy:** if you put nginx in front (as in the [Quickstart](/run/run-a-host/quickstart/)), make sure it routes `/health` to the Host's health server on port `8080`, not to DefraDB on `9181`. Otherwise the probe reaches DefraDB, which doesn't answer `/health` the way the dashboard expects. +- **Reverse proxy:** if you put nginx in front (as in the [Quickstart](/run/run-a-host/quickstart/)), make sure it routes `/health` to the Host client's health server on port `8080`, not to DefraDB on `9181`. Otherwise the probe reaches DefraDB, which doesn't answer `/health` the way the dashboard expects. Confirm the fix by running the same probe the dashboard runs, from outside your server: