Skip to content

Customizing Onion Services container images

The Onion Service container images and configurations provided by the Onimages project can be easily customized.

Customized images

Custom images can be easily built atop the ones provided by Onimages.

Example Dockerfile changing how C Tor is invoked:

FROM containers.torproject.org/tpo/onion-services/onimages/tor:alpine
CMD [ "--RunAsDaemon", "0", "--HiddenServiceDir", "/var/lib/tor/myservice", "--HiddenServicePort", "443 myhostname:443" ]

Docker with custom configuration

C Tor

C Tor images comes up with a single Onion Service defined with the following configuration:

HiddenServiceDir /var/lib/tor/onion
HiddenServicePort 80 httpd:80

This can be overridden when invoking the container, like this:

docker run -d --net tor --mount type=volume,src=tor,target=/var/lib/tor \
  tor \
  --HiddenServicePort 80 httpd:8000 \
  --HiddenServicePort 443 httpd:8443 \

You can even provide a configuration file, by mounting it at /etc/tor/torrc and invoking with this command:

podman run --net tor \
  --mount type=volume,src=tor,target=/var/lib/tor \
  --mount type=bind,src=tor/debian/torrc,target=/etc/tor/torrc \
  tor -f /etc/tor/torrc

Arti with custom configuration

A single Onion Service is defined by default in the Arti container image:

proxy_ports = [
    # Forward HTTP port on the service to the rewriting proxy
    # This does not work as of 2025-04-02, since Arti does not support
    # hostnames in proxy destinations
    #
    # Details at https://gitlab.torproject.org/tpo/core/arti/-/issues/1921
    #["80", "httpd:80"],

    # Workaround until Arti does not support hostnames in proxy destinations
    ["80", "10.89.1.2:80"],
]

The only way to override this is by mounting a config file into the container and passing it with the $ARTI_CONFIG environment variable:

export ARTI_CONFIG=/srv/arti/configs/custom.toml
docker run -d --net onimages --name arti \
  --ip=10.89.1.4 \
  --mount type=volume,src=arti,target=/home/arti \
  --mount type=bind,src=custom.toml,target=/srv/arti/configs/custom.toml \
  --env=ARTI_CONFIG \
  arti:alpine

Another option is to create an environment file, like .env, adding the ARTI_CONFIG there and running the container with --env-file=.env instead of --env=ARTI_CONFIG.

Docker Compose with custom configurations

Customization with the provided configuration is done with an .env file in the project folder.

Example .env contents:

# Custom Arti configuration
ARTI_CONFIG=/srv/arti/configs/custom.toml

# Custom C Tor config
TORRC=/etc/tor/custom.torrc

The custom configuration files should be placed in arti or tor folders, as these are automatically mounted inside the containers when using Compose.

Examples:

  • arti/custom.toml: will be mounted inside the container as /srv/arti/configs/custom.toml in the arti container.
  • tor/custom.torrc: mounted as /etc/tor/custom.torrc inside the tor container.

If you plan to manage these files with Git, make sure to review the default .gitignore rules in the repository.