Merge branch 'fix/docker-compose' into 'main' (7b19767a) · Commits · The Tor Project / Onion Services / Onimages

.gitignore

+3 −0

Original line number	Diff line number	Diff line
		.env
		arti/*.toml
		tor/*.torrc

README.md

+75 −7

Original line number	Diff line number	Diff line
		# Onimages: Onion Service container images

		Container images readily available to run [Onion Services][] using runtimes
		such as [Podman][] and [Docker][].
		such as [Podman][] and [Docker][]:

		These are not official Tor container images, and some of them even rely
		* These are non-official Tor container images, and some of them even rely
		on packages not from the official Tor repositories.

		They are tuned specifically for Onion Service usage (although with some
		* They are tuned specifically for Onion Service usage (although with some
		customization they could be adapted to other purposes).

		* [Regularly built][schedule], usually in a daily basis.

		[Onion Services]: https://community.torproject.org/onion-services/
		[Docker]: https://docs.docker.com
		[Podman]: https://podman.io
		[schedule]: https://gitlab.torproject.org/tpo/onion-services/onimages/-/pipeline_schedules

		## Usage examples

		@@ -122,7 +125,7 @@ cloning this repository:
		git clone https://gitlab.torproject.org/tpo/onion-services/onimages.git
		cd onimages

		A sample [Compose file](docker-compose.yml) is provided, comes with a demo HTTP
		A sample [Compose file][docker-compose.yml] is provided, comes with a demo HTTP
		server, and can be used with

		docker-compose up -d
		@@ -140,9 +143,13 @@ Getting the Onion Service address (Arti):
		Testing these addresses can be done as usual, like stated in the previous
		section.

		[docker-compose.yml]: https://gitlab.torproject.org/tpo/onion-services/onimages/-/blob/main/docker-compose.yml

		## Defaults and overrides

		### C Tor
		### Docker

		#### C Tor

		C Tor images comes up with a single Onion Service defined with the
		following configuration:
		@@ -165,6 +172,67 @@ and invoking with this command:
		--mount type=bind,src=tor/debian/torrc,target=/etc/tor/torrc \
		tor -f /etc/tor/torrc

		#### Arti

		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

		Customization with the [provided configuration][docker-compose.yml] is done
		with an [.env file][] in the project folder.

		Example `.env` contens:

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

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

		[.env file]: https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#env-file

		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.

		[Git]: https://git-scm.com
		[.gitignore rules]: https://gitlab.torproject.org/tpo/onion-services/onimages/-/blob/main/.gitignore?ref_type=heads

		## Tips

		Sometimes is useful to get `tor`'s UID and GID:

arti/alpine/Dockerfile

+1 −1

Original line number	Diff line number	Diff line
		#
		# Dockerfile for an Arti container.
		# Dockerfile for an Arti Alpine container.
		#
		# Copyright (C) 2025 The Tor Project, Inc.
		#

docker-compose.yml

+19 −9

Original line number	Diff line number	Diff line
		@@ -6,6 +6,14 @@
		version: '3'

		services:
		httpd:
		#image: "onimages/httpd"
		image: "containers.torproject.org/tpo/onion-services/onimages/httpd"

		build:
		context: httpd
		dockerfile: Dockerfile

		arti:
		#image: "onimages/arti:alpine"
		image: "containers.torproject.org/tpo/onion-services/onimages/arti:alpine"
		@@ -15,7 +23,7 @@ services:
		# dockerfile: Dockerfile

		volumes:
		- ./arti/debian:/srv/arti/configs
		- ./arti:/srv/arti/configs
		- arti:/home/arti

		networks:
		@@ -23,8 +31,11 @@ services:

		restart: always

		depends_on:
		- httpd

		environment:
		ARTI_CONFIG: /srv/arti/configs/${ARTI_CONFIG:-onionservice.toml}
		ARTI_CONFIG: ${ARTI_CONFIG:-/srv/arti/configs/alpine/onionservice.toml}

		tor:
		#image: "onimages/tor:alpine"
		@@ -35,7 +46,7 @@ services:
		# dockerfile: Dockerfile

		volumes:
		- ./tor/debian:/etc/tor
		- ./tor:/etc/tor
		- tor:/var/lib/tor

		networks:
		@@ -43,13 +54,12 @@ services:

		restart: always

		httpd:
		#image: "onimages/httpd"
		image: "containers.torproject.org/tpo/onion-services/onimages/httpd"
		depends_on:
		- httpd

		build:
		context: httpd
		dockerfile: Dockerfile
		entrypoint: "/usr/bin/tor -f ${TORRC:-/etc/tor/alpine/torrc}"

		command: ''

		networks:
		onimages: