Skip to content

Onionspray Quick Start Tutorial

Step 0: requirements

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 (sudo apt install git on Debian-based systems).

Step 1: download Onionspray's repository

Use Git do clone Onionspray's source code, then enter on the folder:

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

Step 2: build the necessary executables

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, you may find it manually by looking in the opt/ folder. Please open a ticket or send a merge request if your system is currently unsupported.

The build scripts can also be invoked directly.

Example using Debian trixie:

./opt/build-debian-trixie.sh

Detailed installation procedures can be found at the installation guide.

Step 3: create your first onionsite proxy!

Creating a basic Onionspray project can be done with a single command:

./onionspray create <project> <domain> [vanity-prefix]

Example:

./onionspray create myproject mydomain.com myd

This will create an onionsite configuration named myproject which will proxy through the mydomain.com website using a .onion address starting with myd.

Note that the vanity address prefix should not be too big, otherwise it will take a long time to generate the address. As a rule of thumb, let it usually be no longer than 6 chars, and up to 7 chars if you really know what you're doing.

The [vanity-prefix] parameter is entirely optional. You can use something like this to use a random address without a given prefix:

./onionspray create myproject mydomain.com

Step 4: generate startup scripts

Run:

./onionspray script

... which will generate startup and housekeeping scripts; read them for installation instructions.

Step 5: start your server

Run:

./onionspray start myproject

... to start your server; then do:

./onionspray maps myproject

... to see what onion address to connect to.

Wait around one minute for the service bootstrap and then open the address in your favourite Tor-enabled browser!

Step 6: optionally get a CA-validated HTTPS certificate

Onionspray already generates a self-signed HTTPS certificate for each proxied website, valid for 365 days by default and which may work for testing purposes, sometimes even for production environments.

In order to get a certificate validated by a Certificate Authority (CA), check this guide.

References

Other (possibly outdated, written for EOTK) installation references: