Skip to content

Commit 914b9fc

Browse files
Docs: replace the Serve and Funnel images with one diagram (#397)
* Docs: replace the Serve and Funnel images with one diagram and explanation * Docs: redraw the Serve and Funnel diagram with a clearer layout * Docs: simplify the Serve and Funnel diagram --------- Co-authored-by: Bart <57799908+crypt0rr@users.noreply.github.com>
1 parent ebb35db commit 914b9fc

4 files changed

Lines changed: 103 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -340,22 +340,38 @@ From the service directory, run `docker compose down --volumes`. To remove the s
340340

341341
## Tailscale Serve and Funnel
342342

343-
[Tailscale Serve](https://tailscale.com/kb/1312/serve) routes traffic from other devices in your Tailnet to a service on one device. [Tailscale Funnel](https://tailscale.com/kb/1223/funnel) routes traffic from the public internet to that service, so people without Tailscale can reach it.
343+
Every stack has two containers that share one network: a Tailscale container and the application. [Tailscale Serve](https://tailscale.com/kb/1312/serve) and [Tailscale Funnel](https://tailscale.com/kb/1223/funnel) are two ways to let other people reach the application through the Tailscale container.
344344

345-
Stacks that use Serve keep Funnel off (`"AllowFunnel":{"$${TS_CERT_DOMAIN}:443":false}` in `compose.yaml`), so they are reachable from your Tailnet only. Umami has an opt-in public mode; see its README.
345+
![Diagram with two paths into a ScaleTail stack. Path 1, Serve: a device in your Tailnet opens https://<service>.<tailnet>.ts.net, and Serve in the Tailscale container forwards the request to the application at 127.0.0.1:80. Path 2, Funnel: a visitor on the internet reaches the same Serve through a Funnel relay server run by Tailscale, but only when AllowFunnel is true.](images/tailscale-serve-funnel.svg)
346346

347-
To make a service reachable from the internet:
347+
### Serve: your Tailnet only
348+
349+
1. A device in your Tailnet opens `https://<service>.<tailnet>.ts.net`. The traffic travels through Tailscale, encrypted by WireGuard.
350+
2. The Tailscale container receives it on port 443 and ends the HTTPS connection with a certificate for that name.
351+
3. Serve forwards the request to the application. Both containers share one network namespace, so the application is at `127.0.0.1` and its internal port, for example `127.0.0.1:80`.
352+
353+
Serve is on in every stack that sets `TS_SERVE_CONFIG`. Only devices in your Tailnet can use it, and your Tailnet policy can restrict them further.
354+
355+
### Funnel: the public internet
356+
357+
Funnel is off by default. Stacks that use Serve keep it off with `"AllowFunnel":{"$${TS_CERT_DOMAIN}:443":false}` in `compose.yaml`. Umami has an opt-in public mode; see its README.
358+
359+
When you turn Funnel on, a second path opens next to the first:
360+
361+
1. A visitor without Tailscale opens the same address. The name resolves to a Funnel relay server run by Tailscale, not to your machine.
362+
2. The relay opens a TCP proxy to your Tailscale container. It passes the traffic on and cannot read it, because the HTTPS connection still ends in your container.
363+
3. From there, the request follows the same Serve route to the application.
364+
365+
The Serve route does not change. Funnel only adds a way in for visitors from outside your Tailnet.
366+
367+
### Turn Funnel on
348368

349369
1. Add `funnel` to `nodeAttrs` in your Tailnet policy file for the device, as described in [Tailscale Funnel](https://tailscale.com/kb/1223/funnel).
350370
2. In `compose.yaml`, change `false` to `true` in the `AllowFunnel` line.
351371
3. Recreate the stack with `docker compose up -d --force-recreate`.
352372

353373
Funnel is in beta and listens only on ports 443, 8443, and 10000. It requires MagicDNS and HTTPS certificates, as in the Quick Start. Anyone on the internet can then reach the application, so turn on its login first.
354374

355-
![Diagram of Tailscale Funnel: a client on the public internet reaches a controlled gateway, which exposes one service in the Tailnet, while private services get no access.](images/tailscale-funnel.png)
356-
357-
![Diagram of Tailscale Serve: a Tailnet node reaches a lightweight web service through Serve with private access only. Funnel, shown separately, is the only part that publishes a service to the public internet.](images/tailscale-serve.png)
358-
359375
## Documentation
360376

361377
In this repository:

‎images/tailscale-funnel.png‎

-45.6 KB
Binary file not shown.

‎images/tailscale-serve-funnel.svg‎

Lines changed: 80 additions & 0 deletions
Loading

‎images/tailscale-serve.png‎

-48.4 KB
Binary file not shown.

0 commit comments

Comments
 (0)