From 8793362b5f9574615cfbe62ffb64d856a136d767 Mon Sep 17 00:00:00 2001
From: weishu <twsxtd@gmail.com>
Date: Wed, 21 Jan 2026 20:08:10 +0800
Subject: [PATCH] docs: update installation guide and fix environment variable
 references (#85)

- Replace outdated WEBAPP_URL with HAPI_PUBLIC_URL in server and web READMEs
- Add CLI version verification steps in prerequisites section
- Enhance Cloudflare Tunnel documentation with quick and named tunnel examples
- Add --protocol http2 recommendation for tunnel stability
- Include pm2 alternative for runner process management
- Add Telegram Mini App troubleshooting notes and verification steps
---
 docs/guide/installation.md | 52 ++++++++++++++++++++++++++++++++++++++
 server/README.md           |  2 +-
 web/README.md              |  4 +--
 3 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index e0d02994..188242e9 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -6,6 +6,19 @@ Install the HAPI CLI and set up the server.
 
 - Claude Code, OpenAI Codex CLI, or Google Gemini CLI installed
 
+Verify your CLI is installed:
+
+```bash
+# For Claude Code
+claude --version
+
+# For OpenAI Codex CLI
+codex --version
+
+# For Google Gemini CLI
+gemini --version
+```
+
 ## Install the CLI
 
 ```bash
@@ -157,10 +170,33 @@ If you prefer not to use the public relay (e.g., for lower latency or self-manag
 
 https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
 
+**Quick tunnel** (temporary URL, changes on restart):
+
+```bash
+# Install cloudflared: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
+cloudflared tunnel --protocol http2 --url http://localhost:3006
+```
+
+Copy the generated URL and set it:
+
 ```bash
 export HAPI_PUBLIC_URL="https://your-tunnel.trycloudflare.com"
 hapi server
 ```
+
+**Named tunnel** (persistent URL):
+
+```bash
+# Create and configure a named tunnel
+cloudflared tunnel create hapi
+cloudflared tunnel route dns hapi hapi.yourdomain.com
+
+# Run the tunnel
+cloudflared tunnel --protocol http2 run hapi
+```
+
+> **Note:** Use `--protocol http2` instead of QUIC (the default) to avoid potential timeout issues with long-lived connections.
+
 </details>
 
 <details>
@@ -205,6 +241,11 @@ hapi server
 
 Then message your bot with `/start`, open the app, and enter your `CLI_API_TOKEN`.
 
+**Troubleshooting:**
+
+- If binding fails, verify `HAPI_PUBLIC_URL` is accessible from the internet
+- Telegram Mini App requires HTTPS (not HTTP)
+
 ### Runner setup
 
 Run a background service for remote session spawning:
@@ -222,6 +263,17 @@ With the runner running:
 - You can spawn sessions remotely from the web app
 - Sessions persist even when the terminal is closed
 
+<details>
+<summary>Alternative: pm2</summary>
+
+If you prefer pm2 for process management:
+
+```bash
+pm2 start "hapi runner start --foreground" --name hapi-runner
+pm2 save
+```
+</details>
+
 ### Voice assistant setup
 
 Enable voice control:
diff --git a/server/README.md b/server/README.md
index 662fe7f4..c25bfbc3 100644
--- a/server/README.md
+++ b/server/README.md
@@ -209,7 +209,7 @@ The server build output is `server/dist/index.js`, and the web assets are in `we
 
 ## Networking notes
 
-- Telegram Mini Apps require HTTPS and a public URL. If the server has no public IP, use Cloudflare Tunnel or Tailscale and set `WEBAPP_URL` to the HTTPS endpoint.
+- Telegram Mini Apps require HTTPS and a public URL. If the server has no public IP, use Cloudflare Tunnel or Tailscale and set `HAPI_PUBLIC_URL` to the HTTPS endpoint.
 - If the web app is hosted on a different origin, set `CORS_ORIGINS` (or `HAPI_PUBLIC_URL`) to include that static host origin.
 
 ## Standalone web hosting
diff --git a/web/README.md b/web/README.md
index 65ef38e4..40fbec6d 100644
--- a/web/README.md
+++ b/web/README.md
@@ -113,7 +113,7 @@ bun run dev:web
 ```
 
 If testing in Telegram, set:
-- `WEBAPP_URL` to the public HTTPS URL of the dev server.
+- `HAPI_PUBLIC_URL` to the public HTTPS URL of the dev server.
 - `CORS_ORIGINS` to include the dev server origin.
 
 ## Build
@@ -135,7 +135,7 @@ bun run build:web -- --base /<repo>/
 ```
 
 2. Deploy `web/dist` to your static host.
-3. Set server CORS to allow the static origin (`WEBAPP_URL` or `CORS_ORIGINS`).
+3. Set server CORS to allow the static origin (`HAPI_PUBLIC_URL` or `CORS_ORIGINS`).
 4. Open the static site, click the top-right Server button on the login screen, and enter the hapi server origin.
 
 Clear the server override in the same dialog to return to same-origin behavior.