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: