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. Generate a TLS certificate

   Tailscale can provision a Let’s Encrypt certificate for your machine’s Tailscale hostname:

   tailscale cert your-hostname.tail12345.ts.net

   This writes your-hostname.tail12345.ts.net.crt and .key to the current directory. Tailscale Serve uses these automatically — you don’t need to configure them manually.

   Tip

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

2. Start Tailscale Serve

   Proxy HTTPS traffic to the local PizzaPi port (default 7492):

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

   The web UI is now available at:

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

   Tailscale handles TLS termination and certificate renewal automatically.

3. Update allowed origins

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

   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
   cd packages/server && bun run start

   Caution

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

4. 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 --https=443 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