Docker Tor Hidden Service (Modernized)

A secure, lightweight, and modern Docker image for running Tor Hidden Services (Onion Services) with Vanguards protection.

Features

• Lightweight: Built on python:3.11-alpine (latest stable).
• Secure: "Fail-fast" entrypoint script that validates all configuration before starting.
• Vanguards Ready: Includes Vanguards for active defense against deanonymization attacks.
• No Magic: dynamic configuration via standard entrypoint.sh — no opaque Python wrappers.
• Multi-Arch: Supports amd64 and arm64.

Usage

Quick Start (Docker Compose)

version: '3.8'
services:
  tor:
    build: .
    environment:
      # Format: ExternalPort:ContainerName:InternalPort
      - HIDDEN_SERVICE_HOSTS=80:my-web-server:80
      - TOR_CONTROL_PASSWORD=secure_password
    volumes:
      - tor-data:/var/lib/tor/
    depends_on:
      - web

  # Example Web Server
  web:
    image: nginx:alpine
    container_name: my-web-server

  # Vanguards Sidecar (Optional but Recommended)
  vanguards:
    build: .
    command: vanguards --control_ip tor-service --control_port 9051 --control_pass secure_password
    volumes:
      - tor-data:/var/lib/tor/
    depends_on:
      - tor
    restart: unless-stopped

volumes:
  tor-data:

Environment Variables

Variable	Description	Example
HIDDEN_SERVICE_HOSTS	Space-separated list of services to expose. Format: ExtPort:Host:IntPort	80:web:80 22:ssh:22
TOR_CONTROL_PASSWORD	Password for the Tor Control Port (9051). Automatically hashed.	my_secret_password
TOR_DATA_DIR	Location of Tor data (keys, state). Default: /var/lib/tor	/var/lib/tor

Getting your Onion Address

Once running, the Tor service generates your keys automatically.

docker exec <container_name> cat /var/lib/tor/hidden_service/hostname

Checking Vanguards

Verify that Vanguards is connected and pinning your guards:

docker logs vanguards-sidecar
docker exec vanguards-sidecar cat /vanguards.state

Security Notes

• User: Tor runs as the root user in the container by default in this minimal setup, but drops privileges where possible. (Note: Production setups might refine this to use the tor user exclusively).
• Filesystem: The entrypoint.sh enforces chmod 700 on the hidden service directory to satisfy Tor's security checks.

Credits

Based on the original work by cmehay, but fully refactored to remove dependencies on pyentrypoint, pytor, and onions in favor of standard shell scripts and official binaries.