compose.yml

services:
  tor-pool:
    # Published image, or build locally with: docker compose up -d --build
    image: ghcr.io/lncrawl/tor-pool:latest
    build:
      context: .
      dockerfile: ./docker/Dockerfile
    container_name: tor-pool
    restart: unless-stopped

    environment:
      # Authentication is OFF by default here. Every port below is published to
      # 127.0.0.1, so the only caller is this machine, and minting a token to talk
      # to your own container buys nothing: a plain socks5h://127.0.0.1:9250
      # works and the dashboard opens straight to the pool.
      #
      # Set AUTH_DISABLED=false before you widen any *_PUBLISH line. Left on with
      # the ports open, this hands your Tor bandwidth, the session table and
      # instance control to anyone who can reach them, and there is nothing left
      # for them to guess. Startup prints a banner while it is on, and the
      # dashboard shows an "auth disabled" tag where sign-out normally is.
      AUTH_DISABLED: '${AUTH_DISABLED:-true}'

      # The dashboard login, used once AUTH_DISABLED is false. admin / admin
      # unless you set one, so change it in the same breath as widening
      # API_PUBLISH. Set it to nothing at all (ADMIN_PASSWORD=) and the first boot
      # generates one instead and prints it once to this container's log, which is
      # the safe default for a host that is reachable from anywhere. A password
      # set here is never written to disk.
      #
      # These are provisioned even while authentication is off, so turning it on
      # is a restart and not a second round of setup.
      ADMIN_USER: '${ADMIN_USER:-admin}'
      ADMIN_PASSWORD: '${ADMIN_PASSWORD:-admin}'

      # A fixed proxy credential, for provisioning from files instead of the
      # dashboard. Must start with tp_. Empty means the first boot issues one and
      # prints it.
      PROXY_TOKEN: '${PROXY_TOKEN:-}'

      # How many tor instances to run. Each one is an independent exit identity.
      POOL_SIZE: '${POOL_SIZE:-5}'

      # Serve traffic as soon as this many instances have bootstrapped, instead
      # of waiting for the whole pool.
      MIN_READY: '${MIN_READY:-1}'

      # How a caller with no SOCKS credentials is identified: ip | random | shared
      DEFAULT_SESSION: '${DEFAULT_SESSION:-ip}'

      # Idle sessions are unpinned after this long.
      SESSION_TTL: '${SESSION_TTL:-10m}'

      # One credential-free SOCKS port per instance, at this base plus the instance
      # index, for a caller that cannot send a username — a browser, mainly. Off
      # unless you set it, and it needs the matching ports published below.
      SESSION_PORT_BASE: '${SESSION_PORT_BASE:-}'

      # Move an instance's sessions elsewhere when it is rotated.
      DRAIN_ON_ROTATE: '${DRAIN_ON_ROTATE:-true}'

      # Lock each instance to one exit relay, so its exit IP holds still until it
      # is rotated. Off by default: the instance then depends on that one relay.
      PIN_EXIT_RELAY: '${PIN_EXIT_RELAY:-false}'

      LOG_LEVEL: '${LOG_LEVEL:-info}'

    ports:
      # SOCKS5 proxy — the sticky endpoint your scraper connects to. The username
      # is the session key and the password is a token:
      #   socks5h://my-session:tp_xxxxxxxxxxxxxxxxxxxxxx@127.0.0.1:9250
      # With AUTH_DISABLED on, the password is ignored and may be omitted —
      # socks5h://my-session:x@127.0.0.1:9250, or drop the userinfo entirely and
      # take DEFAULT_SESSION. Keep the username: it is what pins you to one exit.
      - '${SOCKS_PUBLISH:-127.0.0.1:9250}:9250'

      # HTTP/HTTPS CONNECT proxy, for tools without SOCKS support.
      - '${HTTP_PUBLISH:-127.0.0.1:9251}:9251'

      # Per-instance credential-free ports, if SESSION_PORT_BASE is set above. The
      # range has to cover POOL_SIZE, and these take no password at all, so publish
      # them no wider than loopback:
      # - '127.0.0.1:19600-19604:19600-19604'

      # Dashboard and REST API. Loopback, and this is the line that makes the
      # AUTH_DISABLED default above safe — widening it without also setting
      # AUTH_DISABLED=false publishes unauthenticated instance control. Even with
      # a credential there is no TLS here, so the password and every token cross
      # the wire in cleartext: widen this only behind something that terminates it.
      - '${API_PUBLISH:-127.0.0.1:8080}:8080'

    # Persist tor state so restarts re-bootstrap from a cached consensus instead
    # of from scratch. It also holds the credential store, which is what makes a
    # generated password and its tokens survive `down` and `up` — `down -v`
    # destroys them and the next boot generates new ones.
    volumes:
      - tor_data:/var/lib/tor

    healthcheck:
      # Reports unhealthy while no instance can carry traffic.
      test: ['CMD', 'wget', '--spider', '-q', 'http://127.0.0.1:8080/health']
      interval: 30s
      timeout: 5s
      # Generous: a cold pool has to bootstrap over Tor before it is usable.
      start_period: 120s
      retries: 3

volumes:
  tor_data: