diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fbd57fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,268 @@
+# 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.