122 lines
4.4 KiB
Markdown
122 lines
4.4 KiB
Markdown
# Telegram WEB proxy
|
|
|
|
[Инструкция по установке и настройке на русском языке](README.ru.md).
|
|
|
|
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
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
./install.sh
|
|
```
|
|
|
|
The installer asks for:
|
|
|
|
1. the public proxy hostname;
|
|
2. the server's public IPv4 address;
|
|
3. 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:
|
|
|
|
```sh
|
|
./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.
|