Container images HOWTO¶

The following Onion Services container images HOWTO assumes you're using Docker and will use the images provided by the Onimages project.

In the commands below, change docker to podman if you're using Podman; the same for docker-compose (replacing by podman-compose), or simply create temporary aliases:

alias docker=podman
alias docker-compose=podman-compose

Also, for picking specific image tags, check out what's available in the container registry.

Docker (or Podman)¶

1. Create a network¶

Let's start by creating a network to connect containers, useful for passing data between an Onion Service frontend and a HTTP backend containers:

docker network create onimages \
  --subnet=10.89.1.0/24

The --subnet argument is optional for C Tor, but needed by Arti due to a bug preventing the use of hostnames in the configuration.

2. Set up a backend HTTP service¶

A simple backend HTTP image will be used for testing:

docker pull containers.torproject.org/tpo/onion-services/onimages/httpd

The HTTP backend container can be started with

docker run -d --net onimages \
  --ip 10.89.1.2 \
  --name httpd httpd

Again, the --ip argument is optional for C Tor, but needed by Arti as a workaround to the bug mentioned above.

3. Setup an Onion Service with a C Tor container¶

Now download an Tor container image:

docker pull containers.torproject.org/tpo/onion-services/onimages/tor:alpine

Create a volume for the Tor data (which will store the Onion Service keys):

docker volume create tor

Start the container and fork it to the background (we're passing a --ip argument just to be sure to not conflict with the IP we'll pass to the Arti container below):

docker run -d --net onimages --name tor \
  --ip=10.89.1.3 \
  --mount type=volume,src=tor,target=/var/lib/tor tor:alpine

Getting the Onion Service address:

docker exec -it tor cat /var/lib/tor/onion/hostname

The output should be an .onion address like n3cqst5infin4zwp3mf3a4cq6dt2yniwvamlj4nivqibnu3lyvtzpayd.onion.

Give a minute (or less) for the bootstrapping process, then test this address, like using Tor Browser. The output should be like in this screenshot:

4. Setup an Onion Service with an Arti container¶

For Arti containers, the procedure is similar. Download an image:

docker pull containers.torproject.org/tpo/onion-services/onimages/arti:alpine

Then create a volume for the Tor data:

docker volume create arti

Start the container:

docker run -d --net onimages --name arti \
  --ip=10.89.1.4 \
  --mount type=volume,src=arti,target=/home/arti arti:alpine

Get the generated Onion Service address:

docker exec -it arti \
  arti -c /srv/arti/configs/onionservice.toml \
  hss --nickname onimages onion-address

Give some time (~1 minute or less) for the boostrapping phase, then test this address like done with C Tor.

Docker Compose (or Podman Compose)¶

Using the example configuration with Docker (or Podman) Compose requires cloning this repository:

git clone https://gitlab.torproject.org/tpo/onion-services/onimages.git
cd onimages

A sample Compose file is provided, comes with a demo HTTP server, and can be used with

docker-compose up -d

Getting the Onion Service address (C Tor):

docker-compose exec tor cat /var/lib/tor/onion/hostname

Getting the Onion Service address (Arti):

docker-compose exec arti \
  arti -c /srv/arti/configs/onionservice.toml \
  hss --nickname onimages onion-address

Testing these addresses can be done as usual, like stated in the previous section.