webtor-bridge

Self-hosted WebTunnel bridge for use with webtor-rs.

Deploy your own Tor bridge with WebTunnel transport in minutes using Docker.

Quick Start

# 1. Clone this repo
git clone https://github.com/your-org/webtor-bridge.git
cd webtor-bridge

# 2. Generate a random secret path
./generate-secret.sh

# 3. Start the bridge
docker-compose up -d

# 4. Get your bridge line
docker-compose logs tor | grep "Bridge line"

What You Get

After deployment, you'll have:

• A WebTunnel bridge running on port 443
• TLS termination via Caddy (auto-renews Let's Encrypt certs)
• A bridge line you can use with webtor-rs

Configuration

Edit .env before starting:

# Your domain (must point to this server)
DOMAIN=bridge.example.com

# Contact email (for Let's Encrypt and Tor directory)
EMAIL=admin@example.com

# Secret path (auto-generated, keep private!)
SECRET_PATH=YourRandomSecretPath123

# Optional: nickname for your bridge
NICKNAME=MyWebtorBridge

Using with webtor-rs

use webtor::{TorClient, TorClientOptions};

let client = TorClient::new(
    TorClientOptions::webtunnel(
        "https://bridge.example.com/YourRandomSecretPath123".to_string(),
        "YOUR_BRIDGE_FINGERPRINT".to_string(),
    )
).await?;

let response = client.get("https://check.torproject.org/").await?;

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Your Server                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Internet                                                       │
│      │                                                          │
│      ▼ (HTTPS :443)                                             │
│   ┌──────────┐                                                  │
│   │  Caddy   │  ← TLS termination, Let's Encrypt               │
│   └────┬─────┘                                                  │
│        │ (HTTP)                                                 │
│        ▼                                                        │
│   ┌──────────┐                                                  │
│   │ WebTunnel│  ← HTTP Upgrade handler                         │
│   │ Transport│                                                  │
│   └────┬─────┘                                                  │
│        │ (Tor cells)                                            │
│        ▼                                                        │
│   ┌──────────┐                                                  │
│   │   Tor    │  ← Bridge relay                                 │
│   │  Bridge  │                                                  │
│   └────┬─────┘                                                  │
│        │                                                        │
└────────┼────────────────────────────────────────────────────────┘
         │
         ▼
    Tor Network

Requirements

• Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose
• Domain name pointing to your server
• Port 443 open

Files

webtor-bridge/
├── docker-compose.yml    # Main orchestration
├── Dockerfile.tor        # Tor bridge with WebTunnel
├── Caddyfile            # Caddy reverse proxy config
├── torrc.template       # Tor configuration template
├── generate-secret.sh   # Generate random secret path
├── .env.example         # Example environment variables
└── README.md            # This file

Security Notes

• Keep your SECRET_PATH private - it's the URL path to your bridge
• The bridge fingerprint is public (needed for clients to verify)
• Your server IP will be visible to the Tor network as a bridge
• Consider running on a VPS, not your home connection

Monitoring

# View logs
docker-compose logs -f tor

# Check bridge status
docker-compose exec tor cat /var/lib/tor/fingerprint

# Restart
docker-compose restart

Troubleshooting

Bridge not starting

docker-compose logs tor
# Check for port conflicts or config errors

Clients can't connect

1. Verify domain DNS points to your server
2. Check port 443 is open: curl -I https://yourdomain.com
3. Verify secret path matches between server and client

Certificate issues

docker-compose logs caddy
# Caddy auto-renews, but check for rate limits

License

MIT