mtproxy-docker/README.md

# An Up-to-date Telegram MTProto Proxy

[![Docker Pulls](https://img.shields.io/docker/pulls/jahus/mtproxy)](https://hub.docker.com/r/jahus/mtproxy)
[![Docker Image Size](https://img.shields.io/docker/image-size/jahus/mtproxy)](https://hub.docker.com/r/jahus/mtproxy)

An up-to-date MTProto proxy for Telegram, built from official sources with automatic configuration updates.

## Why this image?

The official `telegrammessenger/proxy` image is **outdated** and no longer maintained. This image:

- Built from the **latest sources** from Telegram's GitHub repository
- **Automatic configuration updates** daily at 3 AM
- Support for **random padding** to avoid detection
- Simple configuration via environment variables
- Integrated healthcheck

## Quick Start

### 1. Generate a secret

```bash
head -c 16 /dev/urandom | xxd -ps
```

### 2. Run the proxy

```bash
docker run -d \
  --name mtproxy \
  --restart unless-stopped \
  -p 443:443 \
  -e SECRET=your_generated_secret \
  -v ./mtproxy-data:/data \
  jahus/mtproxy:latest
```

### 3. With docker-compose (recommended)

Create a `docker-compose.yml` file:

```yaml
version: '3.8'

services:
  mtproxy:
    image: jahus/mtproxy:latest
    container_name: mtproxy
    restart: unless-stopped
    ports:
      - "443:443"
      - "8888:8888"
    environment:
      - SECRET=${SECRET}
      - PROXY_TAG=${PROXY_TAG:-}
      - WORKERS=2
      - PORT=443
      - STATS_PORT=8888
    volumes:
      - ./data:/data
```

Create a `.env` file:

```bash
# Generate with: head -c 16 /dev/urandom | xxd -ps
SECRET=your_secret_here

# Tag from @MTProxybot (optional)
# PROXY_TAG=your_tag_from_mtproxybot
```

Run:

```bash
docker-compose up -d
```

## Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|--------|--------|
| `SECRET` | 16-byte secret in hex | - | Yes |
| `PROXY_TAG` | Tag from @MTProxybot | - | No |
| `WORKERS` | Number of workers | 1 | No |
| `PORT` | Client port | 443 | No |
| `STATS_PORT` | Statistics port | 8888 | No |

## Proxy Registration

**What is random padding?**  
It's a technique that adds random data to mask MTProxy traffic patterns and avoid detection by ISPs. Recommended in countries with censorship. Just add `dd` before your SECRET in the URL you share or use.

### 1. Register with @MTProxybot

Send your host or IP to [@MTProxybot](https://t.me/MTProxybot) on Telegram

You will receive a **proxy tag** and a link you can share.

## Statistics and Monitoring

### View proxy statistics

```bash
curl http://localhost:8888/stats
```

### View logs

```bash
docker-compose logs -f
```

### Healthcheck

The image includes a healthcheck that automatically verifies the proxy is running:

```bash
docker inspect --format='{{json .State.Health}}' mtproxy
```

## Configuration Updates

### Automatic

Telegram configuration (`proxy-secret` and `proxy-multi.conf`) is **automatically updated daily at 3 AM**.

You can check update logs:

```bash
docker exec mtproxy cat /data/update.log
```

### Manual

To force an immediate update:

```bash
docker exec mtproxy /usr/local/bin/update-config.sh
docker restart mtproxy
```

## Advanced Configuration

### Use a custom port

```yaml
environment:
  - PORT=8443  # Instead of 443
ports:
  - "8443:8443"
```

Don't forget to open the port in your firewall.

### Increase number of workers

For a powerful server with high traffic:

```yaml
environment:
  - WORKERS=4  # or more
```

### Network host mode (alternative)

If you have connectivity issues:

```yaml
version: '3.8'

services:
  mtproxy:
    image: jahus/mtproxy:latest
    container_name: mtproxy
    restart: unless-stopped
    network_mode: host
    environment:
      - SECRET=${SECRET}
      - PROXY_TAG=${PROXY_TAG:-}
      - WORKERS=2
      - PORT=443
      - STATS_PORT=8888
    volumes:
      - ./data:/data
```

## File Structure

```
~/mtproxy/
├── docker-compose.yml
├── .env
└── data/
    ├── proxy-secret       # Telegram config (auto-updated)
    ├── proxy-multi.conf   # Telegram config (auto-updated)
    └── update.log         # Update logs
```

## Security

### Restrict stats access

By default, port 8888 (stats) is exposed. To limit it to localhost only:

```yaml
ports:
  - "443:443"
  - "127.0.0.1:8888:8888"  # Accessible only locally
```

## Image Updates

To update to the latest version:

```bash
docker-compose pull
docker-compose up -d
```

## Usage Examples

### Simple proxy for personal use

```yaml
version: '3.8'
services:
  mtproxy:
    image: jahus/mtproxy:latest
    restart: unless-stopped
    ports:
      - "443:443"
    environment:
      - SECRET=abc123def456...
    volumes:
      - ./data:/data
```

### High-performance proxy

```yaml
version: '3.8'
services:
  mtproxy:
    image: jahus/mtproxy:latest
    restart: unless-stopped
    ports:
      - "443:443"
      - "127.0.0.1:8888:8888"
    environment:
      - SECRET=abc123def456...
      - PROXY_TAG=xyz789...
      - WORKERS=8
    volumes:
      - ./data:/data
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 2G
```

## Support

- Report bugs: [GitHub Issues](https://github.com/darthjahus/mtproxy-docker/issues)
- Discussions: [GitHub Discussions](https://github.com/darthjahus/mtproxy-docker/discussions)

This image is not officially affiliated with Telegram.