Install the control plane

This procedure installs an immutable, release-matched Compose deployment. Run it on a prepared Linux host after completing Plan your deployment.

Keep the launcher on disk long enough to verify and inspect it:

curl -fsSL https://get.tunnex.io -o get.sh
curl -fsSL https://get.tunnex.io/SHA256SUMS -o SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
less get.sh
sudo sh get.sh

The installer validates the signed release descriptor and pins the API, web, edge, gateway-agent, Compose, and upgrade artifacts to one release. It does not clone the source repository or compile images on the server.

Provide:

1. Public base URL — include http:// or https://; use a DNS hostname for direct HTTPS.
2. Bootstrap administrator email — this becomes the first sign-in identity.
3. SMTP choice — configure delivery now or deliberately skip it.

The installer refuses loopback origins, credentials in the URL, path/query components, and direct https:// to an IP address.

For automation, use environment variables. There is no --yes flag:

curl -fsSL https://get.tunnex.io -o get.sh
sudo env \
  TUNNEX_PUBLIC_BASE_URL=https://vpn.example.com \
  TUNNEX_ADMIN_EMAIL=owner@example.com \
  TUNNEX_SMTP=skip \
  sh get.sh

Skipping SMTP keeps password sign-in available, but email verification, password-reset, and invitation delivery require a manual link handoff until SMTP is configured.

On a database with no users, the API prints a banner headed TUNNEX - FIRST RUN: ADMINISTRATOR ACCOUNT. Store the email and generated password immediately in your password manager.

Do not include the password banner in screenshots, shell transcripts, tickets, or CI output.

The installer creates a tunnex/ directory containing .env, tunnex.yml, release.json, and upgrade.sh.

cd tunnex
sudo docker compose -f tunnex.yml ps
sudo docker compose -f tunnex.yml exec -T api \
  wget -qO- http://127.0.0.1:8080/healthz
sudo docker compose -f tunnex.yml exec -T api \
  wget -qO- http://127.0.0.1:9090/readyz

Expected readiness is ok leader or ok follower. Readiness proves the API can reach PostgreSQL and reports its scheduler role; it is not a WireGuard test and does not prove Redis or UDP reachability.

Also check the public origin:

curl -fsS https://vpn.example.com/healthz
curl -fsS https://vpn.example.com/api/v1/meta

The metadata endpoint is public and contains no credentials. It is useful for edition, protocol, mail, SSO-provider, and release presentation checks.

The documentation fixture is reached through an SSH forward. Production users should see the public DNS name selected during installation.

Open the public URL, enter the one-time administrator credential, and continue with First administrator and organization.

• .env contains supported operator configuration. Restrict it to root or the deployment operator.
• tunnex.yml and release.json are installer-managed release artifacts. Do not hand-edit them; the upgrade helper checks their recorded baseline.
• Long-lived generated secrets live in the tunnex_secrets Docker volume, not as ordinary values in .env.
• PostgreSQL data and secrets require independent backup handling.

1. Keep the original terminal error; do not immediately rerun with changed inputs.
2. Check DNS, clock, disk space, Docker daemon health, and outbound HTTPS.
3. Run sudo docker compose -f tunnex.yml ps only if the install directory was created.
4. Inspect the relevant container log, then remove tokens/passwords before sharing it.
5. Rerun the installer only after correcting the reported preflight failure.

On an established deployment, never delete volumes as a generic repair step. Use Troubleshooting and preserve recovery artifacts.