church-translate/docs/PUBLIC-ACCESS.md

# Letting people off-site watch

**Optional.** Everything works on the building's WiFi without any of this. Read
on only if you want people on cell data, or watching from home, to follow along.

Because each campus runs its own copy, this is a per-campus decision — you can
publish one campus and not another.

---

## The easy way: Cloudflare Tunnel

Free, needs no port forwarding, no firewall changes, no certificate, and no
static IP. It runs on the same Mac as the app.

1. **Install cloudflared**

   ```bash
   brew install cloudflared
   ```

   No Homebrew on that Mac? Download the `cloudflared-darwin-arm64.tgz` binary
   from Cloudflare's releases page and drop it in `/usr/local/bin`.

2. **Log in and create the tunnel**

   ```bash
   cloudflared tunnel login
   cloudflared tunnel create translate-main
   ```

3. **Point a hostname at the app**

   ```bash
   cloudflared tunnel route dns translate-main translate.watersmedia.org
   ```

4. **Run it**

   ```bash
   cloudflared tunnel run --url http://127.0.0.1:3100 translate-main
   ```

   To keep it running after a reboot, `sudo cloudflared service install`.

5. **Tell the app its public name**

   Operator page → **Public address** → `https://translate.watersmedia.org` →
   Save. That is what the QR code encodes, so it must be the public name or the
   code only works for people already on your WiFi.

WebSockets pass through Cloudflare tunnels with nothing extra to configure,
which is the main reason this is the lower-risk option.

For a second campus, repeat with its own name — `translate-north`,
`north.translate.watersmedia.org`.

---

## The other way: a name on your existing reverse proxy

You already run a reverse proxy on the NAS at `10.1.1.4` (Boba-Fett, Synology
DSM) fronting `check.watersmedia.org`. It can front this too, though it means
the traffic goes through the NAS network to reach the booth Mac.

This is what North Attleboro runs as of 2026-10-15, in the **LAN-only** form:
`http://translate.watersmedia.org` works on the building's WiFi at both the
Apollo Beach and North Attleboro sites and nowhere else. Nothing was opened to
the WAN. The pieces, with the exact scripts and a step-by-step runbook under
[`examples/waters-church-na/`](examples/waters-church-na/README.md):

| Piece | Where | What |
| --- | --- | --- |
| Local DNS | UniFi consoles at AB and NA (Settings → Policy Table → DNS) | A record `translate.watersmedia.org` → `10.1.1.4`, TTL 300, created with `unifi-dns-record.py` and a per-console Network API key |
| Proxy rule | DSM → Control Panel → Login Portal → Advanced → Reverse Proxy | HTTP `translate.watersmedia.org:80` → HTTP `10.1.7.39:3100`, WebSocket headers, `X-Forwarded-Host: $http_host`, read timeout 3600 s |
| HTTPS | `/usr/local/etc/nginx/sites-enabled/translate-redirect.conf` on the NAS | `https://` answers a 301 to `http://`; the name has no certificate, so browsers warn before the redirect |

Both NAS pieces come from `boba-fett-translate-proxy.sh`, run as
`ssh -t boba-fett sudo bash translate-proxy.sh` because DSM's reverse-proxy API
is root-only. Going through DSM rather than a hand-edited nginx file means the
rule shows up in the DSM UI and survives DSM updates. DSM adds `Host`,
`X-Real-IP`, `X-Forwarded-For` and `X-Forwarded-Proto` on its own.

Then: Operator page → **Public address** → `http://translate.watersmedia.org`
(no trailing slash), so the QR code and poster use the name instead of the
IP and port.

To let people off-site use the same name later: add a public DNS record for
`translate.watersmedia.org` pointing at the NA WAN address, get a certificate
in DSM (Control Panel → Security → Certificate → Let's Encrypt), replace the
redirect with an HTTPS rule to the same destination, and switch Public address
to `https://`. The app behaves the same either way, including the `/operator`
404 through a proxy.

### If the proxy is plain nginx instead of DSM

DSM writes most of this for you. On a hand-managed nginx the server block
needs all of it:

```nginx
server {
    listen 443 ssl http2;
    server_name translate.watersmedia.org;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://10.1.7.39:3100;      # the booth Mac

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;

        # ---- required: captions ride a WebSocket ----
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        # A sermon is long and mostly silent between sentences. Without this the
        # proxy closes the caption socket after 60s of quiet and every phone in
        # the room reconnects at once.
        proxy_read_timeout  3600s;
        proxy_send_timeout  3600s;

        # Live audio: do not hold HLS segments back.
        proxy_buffering off;
    }
}
```

Either way the booth Mac needs a fixed address or a DHCP reservation, or the
proxy breaks the next time DHCP moves it.

---

## Checking it worked

```bash
curl -s http://translate.watersmedia.org/healthz      # https:// once published
```

Should return `{"ok":true,…}`, the same as `curl -s http://10.1.7.39:3100/healthz`.
A proxy that passes the WebSocket answers `HTTP/1.1 101 Switching Protocols` to:

```bash
curl -si -N -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  http://translate.watersmedia.org/ws | head -1
```

Then open the page on a phone: for the LAN-only setup on the guest WiFi, for a
published one **with WiFi turned off**. That is the real test. If the page loads
but captions never appear, the WebSocket headers are missing. If phones on
guest WiFi cannot connect at all, look at client isolation on that network
before anything else. `/operator` returning 404 through the proxy is by design;
staff use `http://10.1.7.39:3100/operator` on the LAN.