Self-hosted Telegram WEB proxy deployment for Docker and Nginx Proxy Manager. The repository contains no deployment-specific hostname, public address, credential or generated client secret.

Architecture

Telegram Desktop
    -> HTTPS / WebSocket
Nginx Proxy Manager
    -> tg-web-proxy:8088
Ingress
    -> local tproxy-server
    -> local MTProxy
    -> Telegram DCs

Only Nginx Proxy Manager can reach the container on its shared Docker network; the Compose file publishes no host ports. The public fallback page is served only for requests without a query string, so authenticated bridge requests and WebSocket traffic always reach tproxy-server.

Repository contents

quick-install.sh — fresh-VPS installation with Docker and automatic HTTPS;
install.sh — interactive installation on an existing Docker/NPM host;
compose.quick.yml and Caddyfile — optional Caddy frontend for the quick path;
compose.yml and Dockerfile — reproducible, checksum-pinned build;
ingress/ingress.go — canonical ingress used by new installations;
ingress/ingress.js — equivalent emergency implementation;
docs/runbook.md — checks, deployment, rollback and troubleshooting;
docs/incidents/bridge-routing.md — routing regression design note;
scripts/audit-public.sh — scans the working tree and Git history for secrets, deployment identifiers and unexpected address literals.

Installation

Quick installation on a fresh VPS

Use a clean x86_64 VPS running Ubuntu or Debian. Create one direct DNS A record for the proxy hostname, connect to the VPS over SSH, and run:

sudo apt update
sudo apt install -y git
git clone https://gitea.sibdata.ru/dir/telegram-web-proxy-stack.git
cd telegram-web-proxy-stack
sudo ./quick-install.sh

The script asks only for the hostname. It resolves the public IPv4 from DNS, installs Docker from Docker's official package repository, deploys the proxy and Caddy, obtains the TLS certificate, verifies a unique response from this exact proxy instance, and prints the Telegram connection values. Inbound TCP ports 80 and 443 must be allowed by the VPS provider. This is a separate deployment mode and does not require Nginx Proxy Manager.

Run quick-install.sh again after git pull --ff-only to update a quick installation. Do not switch that deployment to install.sh, which is intended for the Nginx Proxy Manager mode below.

Existing Docker host with Nginx Proxy Manager

Requirements:

x86_64 Linux;
Docker Engine with the Compose plugin;
an existing Nginx Proxy Manager container and Docker network;
a lowercase DNS hostname whose A record points to the server;
outbound HTTPS access during the build and first start.

Clone this repository, enter its directory and run:

./install.sh

The installer asks for:

the public proxy hostname;
the server's public IPv4 address;
the Nginx Proxy Manager Docker network, but only when it cannot be detected.

For unattended use, provide the same values with --hostname, --public-ip, --npm-network and --yes.

The two cryptographic secrets are generated locally and remain in the named Docker volume. The generated .env contains only the hostname, public address, network name and capacity settings. The installer does not use an external IP discovery service.

When the container is healthy, the script prints the Nginx Proxy Manager Proxy Host values and the generated client secret. Store that secret securely.

External network access

The build downloads checksum-pinned source archives from the official MTProxy and tproxy-server repositories. At startup, the container downloads Telegram's official proxy secret and routing configuration over HTTPS. No access token or API key is required.

Security check

Never commit .env, access tokens, client secrets, generated bridge URLs, profiles.json, MTProxy secret files or volume backups.

Run this before every public release:

./scripts/audit-public.sh

To check private deployment identifiers without publishing them, create an ignored .audit-private-patterns file with one literal string per line. The audit checks those strings in the working tree while the file stays local.

A clean result is necessary, but it does not replace review of the actual diff.