added jellyfin

docs/authentik-sso.md

@@ -0,0 +1,47 @@
+# Single sign-on with Authentik
+
+TODO: fill in as you go. Outline below so the shape is decided in advance.
+
+## Two ways to protect a service
+
+1. **Native OIDC** — the app speaks OIDC itself (Gitea, Nextcloud,
+   Audiobookshelf, Immich). Better experience: real accounts, real logout,
+   group mapping.
+2. **Forward auth** — the proxy asks Authentik before passing the request
+   through. Works for anything, including apps with no auth at all, but the
+   app has no idea who the user is.
+
+Prefer native OIDC where the app supports it; use forward auth as the
+fallback.
+
+## Native OIDC — the shape
+
+TODO: provider + application setup in Authentik, then the four values every
+app asks for:
+
+- Issuer / discovery URL
+- Client ID
+- Client secret → `.env`, never committed
+- Redirect URI
+
+## Forward auth — the shape
+
+TODO: the Caddy snippet, and which services you apply it to.
+
+## Groups and roles
+
+TODO: how you map Authentik groups to per-app roles, and the admin/user
+split.
+
+## Gotchas
+
+TODO: collect these as you hit them. Known ones worth writing down:
+
+- Locking yourself out of an app whose only admin is now behind SSO — keep a
+  local fallback admin until the flow is proven.
+- Redirect URI mismatches, which usually surface as a generic error.
+
+## Related
+
+- [Reverse proxy with Caddy](reverse-proxy.md)
+- [Cloudflare Tunnel](cloudflare-tunnel.md)

docs/cloudflare-tunnel.md

@@ -0,0 +1,74 @@
+# Cloudflare Tunnel
+
+A tunnel exposes a service to the internet **without opening a port** on your
+router and without a VPS. `cloudflared` makes an outbound connection to
+Cloudflare, and Cloudflare routes traffic back down it.
+
+## When to use it (and when not to)
+
+This is the part most guides skip. A tunnel is **not** a drop-in replacement
+for a reverse proxy on a VPS.
+
+| Use a tunnel for | Use Caddy on a VPS for |
+|---|---|
+| Admin UIs, dashboards | Jellyfin, Plex — any video streaming |
+| Gitea, small web apps | Nextcloud, Immich — large uploads |
+| Anything low-bandwidth | Anything you want unmetered |
+
+Two hard limits drive that split:
+
+- **Upload size.** The free plan caps request bodies at roughly 100 MB. File
+  sync and photo backup break on this, often silently or with a confusing
+  413.
+- **Terms of service.** Cloudflare's terms restrict serving large amounts of
+  non-HTML content — video in particular — through the proxy. Streaming a
+  media library through a tunnel is the single most common way people get
+  their account flagged.
+
+For those services, expose them through a reverse proxy you control.
+
+## Setup
+
+TODO: your preferred flow — dashboard-created tunnel vs. `cloudflared tunnel
+create`. The dashboard route is easier to show on video; the CLI route is
+easier to keep in version control.
+
+```yaml
+services:
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    container_name: cloudflared
+    restart: unless-stopped
+    command: tunnel --no-autoupdate run
+    environment:
+      - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}
+```
+
+The tunnel token is a **real secret** — it grants the ability to route
+traffic into your network. It belongs in `.env`, never in a committed file.
+
+## Routing to a service
+
+Public hostname → service, configured per tunnel:
+
+```
+app.example.com  →  http://<host-or-container>:<port>
+```
+
+TODO: note whether you attach `cloudflared` to each service's compose network
+or run one shared tunnel that reaches services by host IP. The second is
+simpler to maintain; the first is better isolated.
+
+## Auth
+
+Cloudflare Access can sit in front of a tunnel and handle authentication
+before traffic ever reaches the service — useful for apps with weak or no
+built-in auth.
+
+TODO: whether you use Access, or terminate auth at Authentik instead. Note
+that running both is usually redundant.
+
+## Related
+
+- [Reverse proxy with Caddy](reverse-proxy.md)
+- [Single sign-on with Authentik](authentik-sso.md)

docs/reverse-proxy.md

@@ -0,0 +1,57 @@
+# Reverse proxy with Caddy
+
+Every service in this repo publishes a plain HTTP port on the host. Nothing
+in a service's compose file knows or cares about TLS, domains, or
+authentication — that is all handled here, in one place.
+
+This is deliberate: it means you can run any stack in this repo standalone,
+and add a proxy later without touching the compose file.
+
+## The basic pattern
+
+Caddy gets a certificate automatically. For most services, one block is the
+entire configuration:
+
+```caddyfile
+app.example.com {
+    reverse_proxy <host>:<port>
+}
+```
+
+Look up `<port>` in the [service table](../README.md).
+
+TODO: note where your Caddyfile lives and whether Caddy runs on the NAS or
+on the VPS.
+
+## Services that need more
+
+Most apps don't care what's in front of them. A few build absolute URLs or
+make security decisions based on the request, and those need to be told.
+
+**Nextcloud** is the main one — it needs all of:
+
+- `trusted_domains` — the public hostname, or it refuses the request
+- `overwrite.cli.url` — so generated links use the public URL
+- `overwriteprotocol=https` — or it builds `http://` links behind TLS and
+  breaks mixed content
+- `TRUSTED_PROXIES` — the proxy's IP, or every client appears to come from
+  the proxy and rate limiting misfires
+
+Milder cases:
+
+- **Gitea** — `ROOT_URL`, or clone URLs point at the wrong host
+- **Authentik** — knows its own external URL by configuration
+- **Jellyfin** — only if you serve it from a subpath rather than a subdomain
+
+TODO: your `header_up` defaults, and whether you set a shared snippet for
+`X-Forwarded-*`.
+
+## Large uploads
+
+TODO: Caddy's defaults are usually fine, but note any `request_body`
+`max_size` you set for Nextcloud/Immich, plus the matching app-side limit.
+
+## Related
+
+- [Cloudflare Tunnel](cloudflare-tunnel.md) — when you don't want to open a port
+- [Single sign-on with Authentik](authentik-sso.md)