Tailscale Setup

If you’re running PizzaPi on a machine in your Tailscale network, you can use Tailscale Serve to expose the web UI over HTTPS with a valid TLS certificate — no reverse proxy or manual cert management needed.

---

Prerequisites

• A working PizzaPi deployment (see Self-Hosting)
• Tailscale installed and logged in on the host machine
• MagicDNS enabled in your Tailscale admin console (enabled by default)

---

Setup

1. Start Tailscale Serve

   Proxy HTTPS traffic to the local PizzaPi port (default 7492). No manual certificate is needed — Tailscale Serve provisions and renews its own TLS certificate automatically.

   tailscale serve --bg http://localhost:7492

   The web UI is now available at:

   https://your-hostname.tail12345.ts.net/

   Tip

   Find your Tailscale hostname with tailscale status --self or in the admin console.

2. Update allowed origins

   The server validates request origins for security. Add your Tailscale HTTPS URL to PIZZAPI_EXTRA_ORIGINS.

   See the Self-Hosting guide for full details on setting environment variables and override files.

   pizza web (Docker)

   Use config set to persist the extra origin:

   pizzapi web config set extraOrigins "https://your-hostname.tail12345.ts.net"

   Then restart:

   pizzapi web stop && pizzapi web

   Manual Docker Compose

   Add the variable to docker/compose.override.yml:

   services:
     server:
       environment:
         PIZZAPI_EXTRA_ORIGINS: "https://your-hostname.tail12345.ts.net"

   Then restart:

   docker compose -f docker/compose.yml up -d

   Without Docker

   Export the variable before starting the server:

   export PIZZAPI_EXTRA_ORIGINS=https://your-hostname.tail12345.ts.net
   bun install
   bun run build
   cd packages/server && bun run start

   Caution

   Do not include a trailing slash — browser origins never have one.

3. Verify

   Open https://your-hostname.tail12345.ts.net/ in your browser. You should see a valid certificate issued by Let’s Encrypt and the PizzaPi login page.

---

Tailscale Serve Management

# Check current serve config
tailscale serve status

# Stop serving
tailscale serve off

Note

tailscale serve --bg persists across Tailscale restarts, but may need to be re-applied after a machine reboot depending on your OS and Tailscale configuration.

---

Tailscale Funnel (Public Access)

If you want to expose PizzaPi to the public internet (not just your Tailnet), you can use Tailscale Funnel instead of Serve:

tailscale funnel --bg http://localhost:7492

This makes your instance available to anyone at https://your-hostname.tail12345.ts.net/ — no VPN required for visitors.

Caution

Funnel exposes your server to the public internet. Make sure you have authentication enabled (PizzaPi enables it by default) and use a strong password.

---

Development with Tailscale TLS

For contributors running the dev stack, PizzaPi’s Vite config can automatically load Tailscale TLS certificates for the dev server.

1. Generate certificates into the certs/ directory

   sudo tailscale cert \
     --cert-file certs/ts.crt \
     --key-file certs/ts.key \
     your-hostname.tail12345.ts.net

2. Set the extra origins env var

   export PIZZAPI_EXTRA_ORIGINS=https://your-hostname.tail12345.ts.net:5173

3. Start the dev server

   bun run dev

   Vite detects certs/ts.crt and certs/ts.key and serves the UI over HTTPS automatically.

Tip

The certs/ directory is already in .gitignore — your keys won’t be committed accidentally.

---

Troubleshooting

Symptom	Cause	Fix
SSL/certificate error in browser	Tailscale Serve not running, or accessing :7492 directly over HTTPS	Use the default HTTPS URL (port 443) and ensure tailscale serve is active
Blank page	Serve configured with https+insecure:// backend	Use http://localhost:7492 (plain HTTP) as the backend — the server doesn’t speak TLS
”Invalid origin” error	PIZZAPI_EXTRA_ORIGINS doesn’t match the URL, or has a trailing slash	Set it to https://your-hostname.tail12345.ts.net (no trailing slash) and restart
502 Bad Gateway	Tailscale Serve config was lost (e.g. after reboot)	Re-run tailscale serve --bg http://localhost:7492
Port already allocated	Another container or process is using the port	Run docker ps -a --filter "publish=7492" to find the conflict, stop it, then retry
Can’t reach from other Tailnet devices	Tailscale ACLs blocking access	Check your ACL policy allows traffic on port 443
bind: address already in use on :443 for another container	tailscale serve holds 443 on the tailnet IP; lsof does not show it (the bind lives inside tailscaled)	Confirm with netstat -an | grep '\.443 ' and move the other service to a different port

---

Tunnels need their own hostname

Tailscale Serve covers the relay itself, but it cannot cover PizzaPi’s host-based tunnels, which need a wildcard hostname (<label>.<domain>):

$ dig +short abc123.your-host.tail12345.ts.net
(NXDOMAIN — MagicDNS resolves registered node names only)

$ tailscale cert abc123.your-host.tail12345.ts.net
500: invalid domain; must be one of ["your-host.tail12345.ts.net"]

MagicDNS has no wildcard and Tailscale issues certificates only for a node’s own name, so no reverse proxy — Caddy, nginx or otherwise — can serve *.your-host.tail12345.ts.net. Separately, the relay refuses any tunnel domain inside its own cookie scope. Use a different domain for tunnels, pointed at the tailnet IP; see Tunnel TLS.