Clears up exposing port 8080 confusion.

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://<your-server-ip>:8080/health`, using the IP it reads from your registered connection string (the `/ip4/<IP>/...` 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://<your-server-ip>: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`

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:
 

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;

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://<your-server-ip>: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://<your-server-ip>: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") %}