Skip to content

Onionspray installation

Primary supported platforms

  • Debian Trixie
  • Ubuntu 22.04 LTS

Automated installation

Users relying on orchestration tools can use some ready-made Onionspray recipes:

The rest of this guide assumes covers the manual procedure.

Main requirements

Unix-like system, and Git

To setup Onionspray, you'll need to:

  • Have access to a Unix-like system such as Debian with internet access and able to reach the Tor network.
  • Have a basic knowledge to use a Unix-like command line interface (a "terminal", or "shell access").
  • Have Git available in your system:
  • On Debian-based systems, it may be installed with sudo apt install git.
  • On CentOS and other yum-based systems: sudo yum -y install git.
  • On FreeBSD, use pkg install git.
  • On MacOS, install Homebrew and then run brew install git.

Tor and OpenResty

Onionspray requires Recent tor and also recent openresty with the ngx_http_substitutions_filter_module NGINX module enabled1. They simply need to be accessible in the $PATH environment variable.

The following "build" scripts supply that by building these software from sources, but if you prefer you can use the ones provided by packages, or build yourself.

This guide also assumes that you have familiarity with Unix-like systems, especially when using a command line interface, and that you have access to such systems.

Optional requirements

Onionspray have optional requirements, depending on what you want to do:

  • Onionbalance needs to installed and available in your $PATH environmente variable if you want to use softmaps. It may be already available as a package in your distribution and be automatically installed by some of the provided build/installation scripts below, so we recommend you to check that after the installation procedure.

Preparation

Onionspray is installed and invoked directly from it's repository, so the first step is to retrieve it's source code and go to it's folder:

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

You main want to add the onionspray folder into your $PATH, so you can invoke Onionspray anywhere:

export PATH=$PATH:/path/to/onionspray

This way, you can invoke onionspray by simply typing

onionspray

Instead of

./onionspray

Or instead of invoking by it's full path name, such as

/path/tonionspray/onionspray

Platform-independent installation procedure

Onionspray comes with a build command that may detect your system and run the specific dependency resolution and compilation procedures, in a best effort basis:

./onionspray build

If Onionspray cannot find and appropriate build script, check the per-platform instructions below.

Per-platform installation

There are a number of supported platforms, whose build scripts are available in the opt/ folder.

Please open a ticket or send a merge request if your system is currently unsupported.

Building from sources

All installations are currently being built from fresh sources for reasons of development and keeping up to date with core, evolving features. As such, installations make take extensive time to build, especially on slower machines.

Check issue tpo/onion-services/onionspray#33 for details.

Keeping the source code

By default, the Onionspray build procedures will cleanup all dependencies' source code after compilation.

Use the --keep-sources flag on the build scripts to preserve the sources, which can be helpful for debugging, testing and other tinkering. Builds running a second time with this flag tends to complete faster.

Debian 13 (trixie)

In a Debian trixie instance:

./opt/build-debian-trixie.sh

There's also an experimental install-debian-trixie.sh script which uses Tor and OpenResty upstream packages, but this procedure is not entirelly supported right now due to:

Debian 12 (bookworm)

In a Debian bookworm instance:

./opt/build-debian-bookworm.sh

There's also an experimental install-debian-bookworm.sh script which uses Tor and OpenResty upstream packages, but this procedure is not entirelly supported right now due to a dependency in an external NGINX module1.

Debian 11 (bullseye)

In a Debian bullseye instance:

./opt/build-debian-bookworm.sh

Ubuntu 24.04LTS (noble)

Install a ubuntu-24.04.2-live-server-amd64.iso server instance with Git; then:

./opt/build-ubuntu-noble.sh

Ubuntu 22.04LTS (jammy)

Install a ubuntu-22.04.2-live-server-amd64.iso server instance with Git; then:

./opt/build-ubuntu-jammy.sh

There's also an experimental install-ubuntu-22.04.sh script which uses Tor and OpenResty upstream packages, but this procedure is not entirelly supported right now due to a dependency on an externa NGINX module1.

Ubuntu 20.04LTS (focal)

Install a ubuntu-20.04.2-live-server-amd64.iso server instance with Git; then:

./opt/build-ubuntu-focal.sh

Ubuntu 18.04LTS (bionic)

Install a ubuntu-18.04.2-live-server-amd64.iso server instance with Git; then:

./opt/build-ubuntu-bionic.sh

Raspbian 9 (stretch)

./opt/build-raspbian-stretch.sh

CentOS 8.2.2004

Install a minimal server and then:

./opt/build-centos-8.2.2004.sh

FreeBSD 12.1

Install a base server and then:

./opt/build-freebsd-12.1.sh

macOS 10.15 (Catalina)

Install Homebrew; and then:

./opt/build-macos-catalina.sh

macOS 10.14 (Mojave)

Install Homebrew; and then:

./opt/build-macos-mojave.sh

Notes

  1. As of January 2024, the ngx_http_substitutions_filter_module dependency means Onionspray won't work with the official OpenResty packages. Newer Onionspray versions might come without this dependency and fully support upstream packages, relying only on the native OpenResty substitution filters. ↩↩↩↩