🐳 telemt-docker

📢 Сборка образов перенесена в GitLab

Из-за перманентной блокировки GitHub Actions образы теперь собираются в

GitLab CI. GitHub-репозиторий

продолжает существовать как зеркало GitLab.

Подробности: An0nX/telemt-docker#14

A minimal, secure, and production-oriented Docker image for Telemt — a fast MTProto proxy server (MTProxy) written in Rust + Tokio.

Built as a fully static binary and shipped in a distroless runtime image, running as non-root by default.

✨ Features

• 🔐 Secure by default: Distroless runtime + non-root user.
• 🏗 Multi-arch: Supports amd64 and arm64.
• 📦 Fully static binary: Designed for gcr.io/distroless/static:nonroot.
• 🧾 Config-driven: You mount a single configuration file directory and go.
• 📈 Metrics-ready: Supports Telemt metrics port (9090) via config.
• 🧰 Build-time pinning: Upstream repo/ref are configurable via build args.

⚠️ Important Notice

Telemt is a Telegram proxy (MTProto). Operating proxies may be restricted or monitored depending on your country/ISP and may carry legal/operational risks.

You are responsible for compliance with local laws and for safe deployment (firewalling, access control, logs, monitoring).

🚀 Quick Start (Docker Compose)

1. Generate a Secret

openssl rand -hex 16

2. Create Configuration Directory

Refer to the upstream repository for the configuration format and examples:

👉 https://github.com/telemt/telemt

To allow the Telemt API to write configuration changes dynamically (e.g. creating users), you must mount a directory, not just the file. The API performs atomic saves by creating a temporary .tmp file in the same directory and renaming it.

Create the directory, place your config inside, and ensure it is writable by the container:

mkdir ./telemt-config
Create and edit your config inside
touch ./telemt-config/telemt.toml
Grant write permissions so the container's non-root user can modify the config
chmod 777 ./telemt-config
chmod 666 ./telemt-config/telemt.toml

3. Create docker-compose.yml

⚠️ Network mode note:

This configuration uses network_mode: host, which means the container shares

the host's network stack directly. **Published ports (ports: section) are

discarded when using host network mode** — port exposure is controlled entirely

by your telemt.toml configuration (i.e. whichever port Telemt listens on will

be available on the host automatically).

If you need Docker-managed port mapping (e.g. remapping ports, or binding only

to 127.0.0.1), remove network_mode: host to use the default bridge mode

and uncomment the ports section below.

⚠️ Privileged Ports (443) Binding Note:

The base image uses a non-root user by default to minimize the attack vector. If your configuration binds Telemt to port 443 (or any port < 1024), you will encounter a Permission denied (os error 13) error. To fix this, you need to run the container as root by uncommenting user: "root" and commenting out the security_opt: no-new-privileges:true block in the example below.

services:
  telemt:
    image: whn0thacked/telemt-docker:latest
    container_name: telemt
    restart: unless-stopped
# ---------------------------------------------------------------     # Root user requirement for binding privileged ports (<1024)     # The default image runs as 'nonroot' to minimize attack vectors.     # Uncomment the line below to run as root ONLY if you need to bind     # to port 443 and encounter 'os error 13'.     # ---------------------------------------------------------------     # user: "root"
# Telemt uses RUST_LOG for verbosity (optional)     environment:       RUST_LOG: "info"
# ---------------------------------------------------------------     # API Configuration writes (Atomic Config Save)     # The API performs atomic writes (creates a .tmp file and renames it).     # To allow the API to save changes to the config, we MUST mount the      # ENTIRE directory (not just the file) and ensure it is writable.     # We override the default command to point to the mounted file.     # ---------------------------------------------------------------     command: ["/etc/telemt/telemt.toml"]     volumes:       - ./telemt-config:/etc/telemt
# ---------------------------------------------------------------     # Host network mode: the container uses the host's network stack     # directly. The "ports" section is IGNORED in this mode — Telemt     # binds to host ports as specified in telemt.toml.     #     # To use Docker-managed port mapping instead, comment out     # "network_mode: host" and uncomment the "ports" section below.     # ---------------------------------------------------------------     network_mode: host
# ports:     #   - "443:443/tcp"     #   # If you enable metrics_port=9090 in config:     #   # - "127.0.0.1:9090:9090/tcp"
# Hardening     # ---------------------------------------------------------------     # ⚠️ If you uncommented user: &quot;root&quot; above to bind to port 443,     # you MUST comment out the two lines below, as they prevent     # gaining the necessary privileges for binding restricted ports.     # ---------------------------------------------------------------     security_opt:       - no-new-privileges:true     cap_drop:       - ALL     cap_add:       - NETBINDSERVICE     read_only: true     tmpfs:       - /tmp:rw,nosuid,nodev,noexec,size=16m
# Resource limits (optional)     deploy:       resources:         limits:           cpus: "0.50"           memory: 256M         reservations:           cpus: "0.25"           memory: 128M
# File descriptor limits (critical for a high-load server!)     ulimits:       nofile:         soft: 65536         hard: 65536
logging:       driver: json-file       options:         max-size: "10m"         max-file: "3"

4. Start

docker compose up -d

Logs:

docker compose logs -f

⚙️ Configuration

Environment Variables

| Variable | Mandatory | Default | Description | |---|:---:|---|---| | RUST_LOG | No | — | Telemt log level (e.g. info, debug, trace). |

Volumes

| Container Path | Purpose | |---|---| | /etc/telemt | Directory containing the telemt.toml config file. Mounted as a directory (without :ro) to allow the API to securely perform atomic writes. |

Ports

| Port | Purpose | |---:|---| | 443/tcp | Main MTProxy listener (commonly used for TLS-like traffic). | | 9090/tcp | Metrics port (only if enabled in telemt.toml). | | 9091/tcp | API port (only if enabled in telemt.toml). |

Note: When using network_mode: host, Docker does not manage port mapping.

Telemt binds directly to host interfaces/ports as configured in telemt.toml.

The table above lists the default ports for reference only.

🧠 Container Behavior

• ENTRYPOINT: telemt
• CMD: Extracted from the docker-compose.yml (["/etc/telemt/telemt.toml"])

telemt /etc/telemt/telemt.toml

To run a raw docker command without Compose:

docker build -t telemt:local .
docker run --name telemt --restart unless-stopped \
  -p 443:443 \
  -e RUST_LOG=info \
  -v "$PWD/telemt-config:/etc/telemt" \
  --read-only \
  --cap-drop ALL --cap-add NETBINDSERVICE \
  --ulimit nofile=65536:65536 \
  telemt:local /etc/telemt/telemt.toml

🛠 Build

This Dockerfile supports pinning upstream Telemt source:

• TELEMT_REPO (default: https://github.com/telemt/telemt.git)
• TELEMT_REF (default: main)

Multi-arch build (amd64 + arm64)

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t whn0thacked/telemt-docker:latest \
  --push .

Build a specific upstream tag/branch/commit

docker buildx build \
  --build-arg TELEMT_REF=v1.1.0.0 \
  -t whn0thacked/telemt-docker:v1.1.0.0 \
  --push .

🔗 Useful Links

• Telemt upstream: https://github.com/telemt/telemt
• MTProxy ad tag bot: https://t.me/mtproxybot
• Distroless images: https://github.com/GoogleContainerTools/distroless