1. Installing

What you need

A server (virtual or physical) with a fresh installation of Debian 13 or Ubuntu 24.04, 64-bit. A fresh server is best: the installer sets up its own web server and firewall.
Root access (sudo) and some free disk space (the setup check asks for at least 500 MB). The application is light; a small virtual server is enough. A fresh Debian has no curl yet (sudo apt install -y curl), which you need to download the release.
A way for people to reach the server: a public IP address or a DNS name, with UDP 1194 (the VPN) and TCP 8443 (the web interface) allowed through any router or cloud firewall in front of it. SSH stays open.

Installing

Everything below is run on the server. The download page shows the same commands with the current version filled in; replace X.Y.Z here with that version.

1. Download the release into a new directory. The loop fetches the archive, its checksum list and signature, the installer, the uninstaller and the public signing key:

mkdir tunnelry && cd tunnelry
BASE=https://updates.tunnelry.com/releases/X.Y.Z
for f in tunnelry-X.Y.Z.tar.gz SHA256SUMS SHA256SUMS.sig install.sh uninstall.sh release-key.pub.pem; do
  curl -fsSL -O "$BASE/$f"
done

If the server has no internet access, download the same files on another computer and copy them into one directory on the server (for example with scp).

2. Check the key. Compare this fingerprint with the one on the download page, so you know the key is the project's:

openssl pkey -pubin -in release-key.pub.pem -outform DER | sha256sum

3. Run the installer as root, from that directory:

sudo bash install.sh --archive tunnelry-X.Y.Z.tar.gz

The installer verifies the signature of the release before it unpacks anything, installs the packages it needs (nginx, PHP, OpenVPN, easy-rsa, nftables, unbound, sqlite3), creates an unprivileged tunnelry user for the web application, writes the system files and starts the web interface. It takes a few minutes and ends with this:

Tunnelry <version> is installed.

  Open:         https://203.0.113.10:8443
  Certificate:  self-signed; SHA-256 fingerprint 54:6B:02:...
  Setup token:  dZIFQnsv1MLAHFjgJvV1lBvYU8cjqUIJ

Write down the setup token. It is shown once and lets you create the first administrator. If you lose it, run the installer again with --new-token.

The web interface starts with a self-signed certificate, so your browser warns you the first time. Compare the SHA-256 fingerprint in the browser's certificate details with the one the installer printed before you accept.

Options

Option	Meaning
`--public-key FILE`	verify the signature with this Ed25519 public key (use the key published with the release)
`--gui-port PORT`	port of the web interface (default 8443)
`--address HOST`	address shown in the URL and certificate (default: the server's main IPv4 address); use a DNS name if people will reach it by name
`--update-url URL`	where the Updates page looks for new versions (`https` only)
`--new-token`	issue a new one-time setup token
`--force`	continue although the checks found something unusual (other web sites on the machine, another distribution)

Running the installer again is safe: it repairs or refreshes the installation without changing its keys. The installer's log is kept in /var/log/tunnelry-install.log.

What it changed on the server

Everything Tunnelry owns is in a few places, so you always know what it touched:

Place	What
`/opt/tunnelry`	the application (one folder per version, `current` points at the active one)
`/var/lib/tunnelry`	its data: the database, settings, backups
`/etc/tunnelry`	the certificate authority and the server's state (root only)
`/etc/openvpn/server`	the OpenVPN configuration it generates
`/usr/lib/tunnelry`	the privileged helper `vpnctl`
nginx site, PHP pool, sudoers rule, systemd units, nftables table `tunnelry`	generated by Tunnelry and rewritten on update

Next: the setup wizard.