telegram-web-proxy-stack/docs/runbook.md

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.