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.

2.7 KiB Raw Blame History