okunev/tor-proxy repository overview

⁠Tor Proxy with obfs4 (Alpine Linux)

A lightweight, secure, and configurable Tor proxy running on Alpine Linux. This image includes obfs4proxy compiled from source (from Yawning/obfs4) to ensure support for the latest obfuscation protocols.

⁠Versions

• TOR (0.4.9.6)
• obfs4 (master)
• alpine (3.23.4)

⁠Github

https://github.com/aaokunev/tor-proxy⁠

⁠Features

• 🐳 Base: Alpine Linux (Small image size).
• 🛡️ Obfuscation: obfs4proxy built from source (multi-stage build).
• 📋 Logs: Tor logs are redirected to stdout for native Docker logging.
• 💾 Persistence: Handles data persistence via Docker volumes.
• 🔧 Permissions: Entrypoint script automatically fixes volume permissions (no chown needed on host).
• 🛠️ Tools: Includes curl, vim, and ping for debugging.

⁠🚀 Quick Start

⁠Option 1: Docker Compose (Recommended)

1. Create a torrc file (see the Configuration⁠ section below).
2. Create a docker-compose.yml:

version: '3.8'

services:
  tor:
    image: okunev/tor-proxy:latest
    container_name: tor-proxy
    restart: unless-stopped
    ports:
      - "9050:9050"       # SOCKS5 Proxy
      - "9053:9053/udp"   # DNS (UDP)
      - "9053:9053/tcp"   # DNS (TCP)
    volumes:
      - ./torrc:/etc/tor/torrc:ro
      - tor_data:/var/lib/tor

volumes:
  tor_data:

1. Run it:

   docker-compose up -d
   

   Copy

⁠Option 2: Docker CLI

docker run -d \
  --name tor-proxy \
  --restart unless-stopped \
  -p 9050:9050 \
  -p 9053:9053/tcp \
  -p 9053:9053/udp \
  -v "$(pwd)/torrc:/etc/tor/torrc:ro" \
  -v tor_data:/var/lib/tor \
  okunev/tor-proxy:latest

⁠⚙️ Configuration (torrc)

This image requires a torrc file mounted at /etc/tor/torrc.

Minimal working example for Docker:

## 1. Logging (Crucial for Docker)
# Send logs to stdout so 'docker logs' works
Log notice stdout

## 2. Network
# Bind to 0.0.0.0 to allow access from outside the container
SocksPort 0.0.0.0:9050
DNSPort 0.0.0.0:9053

## 3. Data Storage
# This path is persistent via the volume defined in docker-compose
DataDirectory /var/lib/tor

## 4. Bridges (Optional but recommended)
UseBridges 1
# Point to the obfs4proxy binary inside the container
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy

# Add your bridges here (Get them from bridges.torproject.org)
# Bridge obfs4 <IP>:<PORT> <FINGERPRINT> cert=<CERT> iat-mode=0

⁠📂 Volumes & Permissions

Note on Permissions: The image includes an entrypoint script. When the container starts, it automatically adjusts the ownership of /var/lib/tor to the internal tor user. You do not need to manually chown your Docker volumes on the host machine.

⁠✅ Verification

Once running, verify that the proxy is working:

1. Check connection via SOCKS5:

curl --socks5-hostname localhost:9050 -s https://check.torproject.org/ | grep -i "congratulations"

2. Check DNS resolution:

dig @localhost -p 9053 google.com

3. View Logs:

docker logs -f tor-proxy

⁠⚠️ Disclaimer

This image is provided "as is". Users are responsible for complying with their local laws and regulations regarding the use of Tor and encryption software.

⁠⏳ Startup Note

After the container starts, the proxy is not available immediately. Tor needs some time to bootstrap and establish the connection. You can watch the bootstrap process in real time with:

docker logs -f tor-proxy