feat: publish generic Telegram WEB proxy stack

2026-10-14 16:37:48 +07:00
commit a91a7ca11a
14 changed files with 1153 additions and 0 deletions
@@ -0,0 +1,31 @@
+# Design note: bridge query routing
+
+## Failure mode
+
+A public fallback handler that matches every `GET /` request also captures the
+authenticated bridge request because the bridge capability is carried in the
+query string. The service may appear healthy while Telegram clients cannot
+connect.
+
+## Required behavior
+
+Serve the fallback page only when the request has no query string:
+
+```go
+if request.Method == http.MethodGet &&
+    request.URL.Path == "/" &&
+    request.URL.RawQuery == "" {
+    servePublicPage()
+}
+```
+
+Requests with bridge parameters, carrier API requests and WebSocket upgrades
+must be proxied to `tproxy-server`.
+
+## Verification
+
+- the public root returns the fallback page;
+- an authenticated bridge request returns the bridge document and disables
+  caching;
+- WebSocket traffic reaches the relay;
+- a healthy admin endpoint is treated as necessary but not sufficient.
@@ -0,0 +1,69 @@
+# Telegram WEB proxy runbook
+
+## Components
+
+| Component | Name | Purpose |
+| --- | --- | --- |
+| Container | `tg-web-proxy` | Runs MTProxy, `tproxy-server` and ingress |
+| Docker volume | `tg_webproxy_data` | Stores generated secrets and runtime data |
+| Ingress port | `8088` | Receives HTTP and WebSocket traffic from NPM |
+
+No Docker host port is published. Nginx Proxy Manager and the proxy container
+must share the external Docker network selected during installation.
+
+## Nginx Proxy Manager
+
+Create a Proxy Host using the values printed by `install.sh`:
+
+| Field | Value |
+| --- | --- |
+| Domain Names | the hostname entered during installation |
+| Scheme | `http` |
+| Forward Hostname / IP | `tg-web-proxy` |
+| Forward Port | `8088` |
+| Websockets Support | enabled |
+| Force SSL | enabled |
+| HTTP/2 Support | enabled |
+| Certificate | a valid certificate for the selected hostname |
+
+## Expected responses
+
+| Request | Expected result |
+| --- | --- |
+| Plain `GET /` | HTTP 200 and the small fallback page |
+| Authenticated `GET /?bridge=...` | bridge page with `Cache-Control: no-store` |
+| Carrier API and WebSocket paths | proxied to `tproxy-server` |
+| Wrong `Host` header | HTTP 421 |
+
+Never paste a bridge capability into tickets, logs or monitoring labels. It is
+derived from the client secret and must be treated as sensitive.
+
+## Health checks
+
+1. Confirm that `tg-web-proxy` is running and healthy.
+2. Request the public root over HTTPS and expect HTTP 200.
+3. Confirm that the TLS certificate validates and HTTP redirects to HTTPS.
+4. Validate an authenticated bridge request from a trusted diagnostic process
+   without printing or persisting the complete URL.
+5. Confirm that a WebSocket upgrade reaches the relay. An invalid test token may
+   be rejected, but it must not return the public fallback page.
+
+## Updating
+
+Pull the reviewed repository revision and run `./install.sh` again. Docker builds
+the new image before replacing the running container. Keep the named volume so
+the client secret remains stable.
+
+## Rollback
+
+Keep the previously built image until the new deployment passes every health
+check. To roll back, restore the previous Compose revision and start it with the
+same `.env` and named volume. Do not recreate the volume during rollback.
+
+## Secret handling
+
+- Keep management-system access tokens short lived and revoke them after use.
+- Keep `client-secret`, `profiles.json`, bridge URLs and MTProxy secret files out
+  of Git.
+- The generated `.env` is for non-secret deployment settings only.
+- Never attach a volume export or management-system backup to a public issue.