tonnamespace/reverse-proxy repository overview

⁠TON Utils Reverse Proxy Docker

🚀 A lightweight Docker image for running the TON Utils Reverse Proxy⁠ – effortlessly serve your websites through TON DNS domains. Perfect for decentralized hosting on the TON blockchain!

⁠🌟 Features

• 🔑 Automatic Private Key Generation: Secure setup in one command.
• 📱 QR Code or Transaction URL: Easy domain linking via wallet scan.
• ⚙️ Config Persistence: Mount volumes for seamless restarts.
• 🌐 TON DNS Integration: Proxy traffic directly to your .ton domain.
• 🛡️ Secure & Simple: Environment-driven config with built-in tunneling.

⁠🚀 Quick Start

⁠Step 1: First Initialization

Create a persistent config directory and initialize the proxy:

mkdir -p ./tonutils-config

docker run -it --rm \
  -v $(pwd)/tonutils-config:/app \
  -e FIRST_INIT=true \
  -e DOMAIN="namespace.ton" \
  tonnamespace/reverse-proxy:latest

This command will:

• ✅ Generate a new private key and config.json.
• 📲 Display a QR code for wallet-based ADNL address setup.
• 💾 Save everything to your local ./tonutils-config directory.

⁠Step 2: Complete Domain Setup

• Scan the QR code with your domain owner's TON wallet app.
• Or, set TX_URL=true during init to get a direct transaction URL instead.

Wait for the transaction to confirm on the TON blockchain (usually ~5-10 seconds).

⁠Step 3: Run the Proxy

Launch the proxy in detached mode:

docker run -d \
  --name tonutils-proxy \
  -p 8765:8765 \
  -v $(pwd)/tonutils-config:/app \
  -e PROXY_PASS="https://namespace.my/" \
  -e EXTERNAL_IP="your_server_ip" \
  tonnamespace/reverse-proxy:latest

Your site is now live at http://namespace.ton! 🎉

⁠⚙️ Environment Variables

⁠Required for First Initialization

⁠Required for Normal Operation

⁠Optional Variables

⁠💡 Complete Setup Example

⁠1. Initialize with QR Code

mkdir -p ./tonutils-config

docker run -it --rm \
  -v $(pwd)/tonutils-config:/app \
  -e FIRST_INIT=true \
  -e DOMAIN="mydomain.ton" \
  tonnamespace/reverse-proxy:latest

⁠2. Initialize with Transaction URL

mkdir -p ./tonutils-config

docker run -it --rm \
  -v $(pwd)/tonutils-config:/app \
  -e FIRST_INIT=true \
  -e DOMAIN="mydomain.ton" \
  -e TX_URL=true \
  tonnamespace/reverse-proxy:latest

⁠3. Run the Proxy

docker run -d \
  --name my-ton-proxy \
  -p 8765:8765 \
  -v $(pwd)/tonutils-config:/app \
  -e PROXY_PASS="https://mywebsite.com/" \
  -e EXTERNAL_IP="1.2.3.4" \
  -e PORT="8765" \
  tonnamespace/reverse-proxy:latest

⁠🐳 Docker Compose Example

For easier management, use this docker-compose.yml:

version: '3.8'

services:
  # First: Run initialization
  tonutils-init:
    image: tonnamespace/reverse-proxy:latest
    container_name: tonutils-init
    volumes:
      - ./tonutils-config:/app
    environment:
      - FIRST_INIT=true
      - DOMAIN=namespace.ton
      - TX_URL=false  # Set to true for transaction URL
    profiles:
      - init
    stdin_open: true
    tty: true

  # Then: Run the proxy
  tonutils-proxy:
    image: tonnamespace/reverse-proxy:latest
    container_name: tonutils-proxy
    ports:
      - "8765:8765"
    volumes:
      - ./tonutils-config:/app
    environment:
      - PROXY_PASS=https://namespace.my/
      - EXTERNAL_IP=YOUR_HOST_EXTERNAL_IP
      - LISTEN_IP=0.0.0.0
      - PORT=8765
    restart: unless-stopped
    profiles:
      - proxy

Commands:

• Initialization: docker-compose --profile init up tonutils-init
• Proxy: docker-compose --profile proxy up -d tonutils-proxy

⁠📝 Configuration

The container handles config.json automatically:

• Init Mode: Generates a fresh config with a private key.
• Proxy Mode: Merges env vars into the existing config.

Example config.json:

{
  "proxy_pass": "https://namespace.my/",
  "private_key": "e7Y4DtgPtJP1UqlI5jGWhrLOotTWa3EjQwNSfh3akCw=",
  "external_ip": "YOUR_HOST_EXTERNAL_IP",
  "listen_ip": "0.0.0.0",
  "network_config_url": "https://ton.org/global.config.json",
  "custom_tunnel_network_config_url": "",
  "port": 8765,
  "tunnel_config": {
    "TunnelServerKey": "qT8TWTeZWdjMd/Qv7xRbfmYnO4xnJgZ4/UEWEU+tXgs=",
    "TunnelThreads": 1,
    "TunnelSectionsNum": 1,
    "NodesPoolConfigPath": "",
    "PaymentsEnabled": false,
    "Payments": {
      // ... payment configuration
    }
  },
  "version": 1
}

⁠🔄 Workflow

1. Initialize 🔧: Run with FIRST_INIT=true to generate config and setup info.
2. Link Domain 🔗: Scan QR or complete transaction to bind ADNL address.
3. Launch Proxy 🚀: Start with your backend URL and external IP.
4. Go Live 🌍: Access your site via the TON domain – no central servers needed!

⁠🛠️ Troubleshooting

Pro Tip: Always tail logs for real-time debugging!

⁠📊 Logs

• View init logs: docker logs tonutils-init
• View proxy logs: docker logs tonutils-proxy
• Follow live: docker logs -f tonutils-proxy

⁠🔒 Security Notes

• 🔐 Private Key Handling: Auto-generated and stored in config.json – back it up!
• 🛡️ Best Practices: Use env vars for secrets; enable Docker secrets in prod.
• 📂 Permissions: Restrict access to your config directory.
• ⚠️ Warning: Never commit config.json to public repos.

⁠🏗️ Building Locally

git clone https://github.com/TON-Namespace/docker-ton-reverse-proxy.git
cd docker-ton-reverse-proxy
docker build -t reverse-proxy .

Test with: docker run -it --rm -e FIRST_INIT=true -e DOMAIN="test.ton" reverse-proxy

⁠🤝 Contributing

We ❤️ contributions! Here's how:

1. 🍴 Fork the repo.
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature).
3. ✏️ Make your changes and commit (git commit -m 'Add amazing feature').
4. 🚀 Push to the branch (git push origin feature/amazing-feature).
5. 📤 Open a Pull Request!

Please ensure tests pass and add docs for new features.

⁠📄 License

This project is licensed under the MIT License⁠ – free to use, modify, and distribute.

⁠🔗 Links

• 🌐 TON Utils Reverse Proxy GitHub⁠
• 📚 TON Documentation⁠
• 🐳 Docker Hub Repo⁠
• 🏠 Project Repo⁠

Built with ❤️ for the TON community. Questions? Open an issue!