Skip to content

Enabling remote access with Tailscale

This guide gets you from "Protequ only works on the site network" to "I can open it from my phone on mobile data". It uses Tailscale, a private network (a tailnet) between your own devices. Protequ joins it with the Tailscale adapter; nothing is opened on your firewall and no traffic is routed through Protequ's servers.

What you end up with

phone (Tailscale app) ──► your tailnet ──► Protequ install ──► web interface
                          outbound connection only, no inbound port
You open https://<node name>.<your tailnet>.ts.net and sign in with your normal Protequ account.

What you need

  • A Tailscale account for the person or organisation that owns the tailnet, and access to its admin console.
  • A Protequ install that can reach the internet over HTTPS (outbound).
  • The Tailscale app on every device you want to connect from, signed in to the same tailnet.
  • Administrator access to the machine running Protequ, because the front door certificate and the sign-in settings are changed once.

The adapter settings themselves are described on its own page; this guide shows the whole path in order.

1. Create an auth key

In the Tailscale admin console, open Settings → Keys → Generate auth key.

  1. Switch on Reusable.
  2. Switch on Tags and choose a tag for Protequ, for example tag:protequ. A tagged machine does not belong to one person, so it keeps working when that person leaves. The tag must exist under tagOwners in the tailnet policy.
  3. Switch on Pre-approved if your tailnet requires administrators to approve new devices.
  4. Generate the key and copy it. It starts with tskey-auth- and is shown only once.

The key only matters at registration

A key lasts at most 90 days, but it is used once, when the node first joins. After that the node keeps working without it. You need a key again only if the node's saved login is lost, for example when its volume is removed.

2. Add the Tailscale node in Protequ

  1. Make sure the Tailscale adapter is installed and running.

  2. Add a device of type Tailscale node and fill in:

    Setting Value
    Auth key (auth_key) the key from step 1
    Hostname (hostname) a short name, for example protequ-site1

    Leave the other settings at their defaults. The front door is exposed on port 443 of the node. 3. Restart the device. Settings are read when the device connects, not live.

The device goes online in Protequ. In the Tailscale console the machine appears under Machines with your tag. Its full name is shown there and looks like protequ-site1.tail1234.ts.net.

Turn off key expiry for the node

A machine registered with a tag normally has key expiry switched off. If the console shows a different state, open the machine's menu and choose Disable key expiry; otherwise the node drops out of the tailnet after about six months.

3. Let Protequ accept the new name

Protequ signs people in through its identity provider, and it only accepts host names it knows. Tell it about the Tailscale name once.

Run the installer and enter the Tailscale name in the extra names / SANs field, together with any addresses you already use. The installer adds the name to the certificate, to the trusted hosts and to the allowed sign-in redirects in one go.

Do these on the machine running Protequ, as administrator.

  1. Add the name to the trusted hosts in the install's .env file, keeping the existing entries:

    OIDC_EXTRA_HOSTS=,192.168.1.90,protequ-site1.tail1234.ts.net

  2. Regenerate the front door certificate and the sign-in settings. Pass every name the install is reached on, including the Tailscale one. openssl must be on PATH.

    .\configure-host.ps1 -Hosts "protequ-host,192.168.1.90,protequ-site1.tail1234.ts.net"

    If it fails, check that certs\nginx\nginx.crt and nginx.key still exist before you restart anything; the script replaces them.

  3. The script rewrites the realm file, but a running identity provider does not re-read it. Add the new name to the sign-in client of the running instance. This opens a shell inside its container:

    docker exec -it pq-keycloak bash

    K=/opt/keycloak/bin/kcadm.sh
$K config credentials --server http://localhost:8080/idp --realm master \
   --user "$KC_BOOTSTRAP_ADMIN_USERNAME" --password "$KC_BOOTSTRAP_ADMIN_PASSWORD"
ID=$($K get clients -r pq -q clientId=pq-server --fields id --format csv --noquotes)
$K update clients/$ID -r pq \
  -s 'redirectUris=["https://protequ-host/signin-oidc","https://192.168.1.90/signin-oidc","https://protequ-site1.tail1234.ts.net/signin-oidc"]' \
  -s 'webOrigins=["https://protequ-host","https://192.168.1.90","https://protequ-site1.tail1234.ts.net"]' \
  -s 'attributes."post.logout.redirect.uris"=https://protequ-host/*##https://192.168.1.90/*##https://protequ-site1.tail1234.ts.net/*'

    Replace the values with the names your install uses and list all of them: these fields are replaced, not appended to. If the bootstrap administrator has been changed, sign in with your own administrator instead.

  4. Recreate the Protequ server so it reads the new trusted hosts, then restart the front door:

    docker compose up -d --no-deps server
docker restart pq-nginx

    Recreating the server makes the adapters announce themselves again, so restart them afterwards.

4. Connect from your phone

  1. Install the Tailscale app and sign in to the same account that owns the tailnet.
  2. Turn off Wi-Fi so the phone is on mobile data.
  3. Open https://protequ-site1.tail1234.ts.net and sign in with your Protequ account.

Certificate warning

The front door certificate is signed by the install's own certificate authority, so a phone that has not been told to trust it shows a warning. Either accept the warning for this site, or install the install's root certificate on the phone.

If it does not work

What you see Cause and fix
Page does not load at all The phone is not on the tailnet, or the access rules do not allow it to reach the Protequ tag on port 443. Check the Tailscale app shows the machine as connected.
Page loads, then an error on sign-in The name is not accepted yet. The server log says Untrusted host header: finish step 3, including recreating the server.
Sign-in reports an invalid redirect The identity provider does not know the name yet. Repeat the client update in step 3.3.
Tailscale says you attempted to log in to a different tailnet You are signed in to Tailscale with a different identity (for example another GitHub account) than the one that owns the tailnet. Sign out and sign in with the owner's account, or use a private window.
Device stays offline, log says the node needs login The auth key is missing, expired or revoked. Create a new key, enter it, restart the device.
The node vanished after an upgrade The node's saved login was lost when the install was redeployed. It registers again with the auth key; delete the old machine entry in the console.
  • Tailscale adapter — settings, security notes and troubleshooting for the adapter itself.