friendlyadmin/onionbalance repository overview

⁠FriendlyAdmin/onionbalance

Onionbalance and Tor neatly packaged in a single Docker image.

Built for Docker Hub automatically by utilizing a GitHub hook, see hooks/build for details.

Onionbalance⁠ is a Tor-specific utility for running a Tor hidden service. It fetches hidden service descriptors from multiple backend .onion addresses and publishes them all under a single frontend (public) .onion address.

Tor on a client will fetch all of the descriptors and choose one to request at random. If the hidden service isn't available under a chosen descriptor - Tor will try another one, until it reaches the service or runs out of decriptors. Effectively performing a randomized round-robin load-balancing.

Onionbalance also allows a hidden service operator to keep the keys of his public .onion address separate from the actual production server.

See Onionbalance docs⁠ for more details.

Docker Hub repo⁠ GitHub repo⁠

⁠Usage

To run the image you must provide an Onionbalance config file onionbalance.config.yaml (see example_onionbalance.config.yaml in this repo) and keys for a frontend (public) .onion address hs_ed25519_secret_key and hs_ed25519_public_key.

The easiest way to run this image is by using Docker Compose utility and a config onionbalance/docker-compose.yaml from this repo⁠.

Or run it as a standalone container like so:

docker container run --read-only -d --name=onionbalance \
    -v onionbalance.config.yaml:/onionbalance/config.yaml:ro \
    -v hs_ed25519_secret_key:/var/lib/hs_data/hs_ed25519_secret_key:ro \
    -v hs_ed25519_public_key:/var/lib/hs_data/hs_ed25519_public_key:ro
    friendlyadmin/onionbalance:latest

⁠Building

To build the image manually run from inside the repo root directory:

docker build \
    --build-arg PYTHON_VERSION=3.9 \
    --build-arg TOR_VERSION=0.4.4.6 \
    --build-arg ONIONBALANCE_VERSION=0.2.0 \
    -t YOUR_DESIRED_IMAGE_TAG \
    .

You must provide PYTHON_VERSION, TOR_VERSION and ONIONBALANCE_VERSION build arguments.

See tags on Docker Hub Python repo⁠ for what Python image versions are available.

See tags on FriendlyAdmin/tor image⁠ for what Tor versions are available.

See Onionbalance repo⁠ for the latest Onionbalance version.

⁠See also

FriendlyAdmin/tor⁠ - General purpose Tor Docker image used in building the Onionbalance image.

FriendlyAdmin/tor-hs⁠ - A pre-made simple Docker Compose configuration for running an Onionbalanced Tor hidden service.