diff --git a/content/run/operations/troubleshooting/index.md b/content/run/operations/troubleshooting/index.md index db3f594..5911301 100644 --- a/content/run/operations/troubleshooting/index.md +++ b/content/run/operations/troubleshooting/index.md @@ -184,6 +184,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 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 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: + +```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 8cefa18..c0d6b10 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 or 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 31d8103..65d18de 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 9c68b90..6cc37fa 100644 --- a/content/run/run-a-host/register/index.md +++ b/content/run/run-a-host/register/index.md @@ -7,6 +7,8 @@ To participate in the Shinzo Network and make your View publicly available, you ## Add the Shinzo Testnet to your wallet +Add the Shinzo Testnet to your browser wallet with the following values: + | Field | Value | | --- | --- | | Network name | `Shinzo` | @@ -18,7 +20,7 @@ To participate in the Shinzo Network and make your View publicly available, you The hosted [Registration app](https://registration.shinzo.network/) runs from any browser and doesn't require port forwarding, so it's the easiest path for Hosts reachable from the public internet. -1. Start your Host client and confirm it's online. +1. Start your Host client 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 client shows as offline even while it's running fine. 1. Open the [Registration app](https://registration.shinzo.network/) and select **Connect** to connect your wallet. 1. Choose **Host** as the role and fill in the requested details. 1. Submit your registration and confirm the transaction in your browser wallet. You should see a successful registration notification. @@ -27,7 +29,7 @@ The hosted [Registration app](https://registration.shinzo.network/) runs from an If your Host is on a private network or you'd rather not route registration through the hosted app, the Host client serves its own registration app on port `8080`. -1. Start your Host with the health/registration port published (`-p 8080:8080`). The default command in [Install](/run/run-a-host/install/) does not publish it. +1. Start your Host client 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 client shows as offline even while it's running fine. 1. Open the [registration page](http://localhost:8080/registration-app) and select **Connect** to connect your wallet. {% admonition(type="info") %}