Media-Server-Setup/HOSTNAME-CHANGE.md

# Changing hostnames safely

Two cases: renaming one subdomain (e.g. `watch.BASE` → `video.BASE`), and moving the whole stack to a new base
domain. Both are mostly `configure.py --full` plus a known list of places outside the repo that hold the name.
Do it between streams: the main host is MediaMTX's WebRTC advertised host, so a main-host change needs a
MediaMTX restart.

## Where hostnames live

### Generated on the server by `configure.py` (regenerated by `--full`, nothing to edit by hand)
| Place | Holds |
|---|---|
| `Caddyfile` | every site block — the source of truth `configure.py` reads back (`# vanguard:<role>` markers) |
| `.env` | `MAIN_HOST`, `WATCH_HOST`, `GIT_HOST`, `BOT_HOST`, `LIVE_HOST`, `APEX_HOST`, `APEX_REDIRECT` |
| `mediamtx.yml` | `webrtcAdditionalHosts: [MAIN_HOST]` (needs a MediaMTX restart to take effect) |
| `docker-compose.yml` → container env | Jellyfin `PublishedServerUrl` (WATCH), Gitea `DOMAIN/ROOT_URL/SSH_DOMAIN` (GIT), bot `WEB_PUBLIC_URL` (BOT), MediaMTX `LIVE_HOST` (text of the "is live" post), act_runner `GITEA_INSTANCE_URL` (GIT). `compose up -d` in the apply recreates the affected containers (seconds each) |
| Caddy TLS | certificates for new names are fetched automatically; old ones linger harmlessly |

### Pages in the repo that derive sibling hosts from the browser's location (label names hard-coded)
| File | Assumes |
|---|---|
| `about/index.html` | `auth.`, `watch.`, `live.`, `git.`, `bot.` + the parent of the current host |
| `dock/index.html` | `auth.` (sign-out), ingest host prefilled from the current host |
| `switchToClone.sh`, `deployLive.sh` | defaults for `git.dumpstervigilantes.rip` / `ovh1.dumpstervigilantes.rip` (override by env/arg, or edit) |
| `README.md`, `FRESH-INSTALL.md` | examples only |
Renaming a *label* (e.g. `watch` → `video`) means editing the first two; changing only the domain does not.

### Outside the repo — must be changed by hand
| System | Setting | Which host |
|---|---|---|
| DNS | A record + CNAMEs | all |
| Discord developer portal | OAuth2 redirect `https://AUTH/source/oauth/callback/discord/` | auth |
| Authentik | Embedded Outpost `authentik_host` | auth |
| Authentik | `Vanguard sites` proxy provider: authentication URL (auth) and **cookie domain** (base) | auth, base |
| Authentik | `Jellyfin` provider redirect URI `https://WATCH/sso/OID/redirect/authentik` | watch |
| Authentik | `Gitea` provider redirect URI `https://GIT/user/oauth2/authentik/callback` | git |
| Jellyfin | SSO-Auth plugin: OID endpoint `https://AUTH/application/o/jellyfin/` | auth |
| Jellyfin | Branding login disclaimer (the form action contains the watch host) | watch |
| Jellyfin | Vanguard Metadata plugin: Public URL, Authentik URL | watch, auth |
| Gitea | Authentication source `authentik`: discovery URL `https://AUTH/application/o/gitea/.well-known/openid-configuration` | auth |
| Gitea runner | registered with the instance URL → `./registerGiteaRunner.sh` again | git |
| Server clone | `git remote set-url origin ssh://git@GIT:2222/techy/Media-Server-Setup.git`; `~/.ssh/config.vanguard` Host line | git |
| Dev box | `git remote set-url origin …` | git |
| Streamers' OBS | dock URL (Custom Browser Docks), dock Settings → ingest host (re-save), clock browser source URL (dock → Timecode band → "Add band + clock source" again), any manual RTMP/SRT configs (copy from the dock) | main |
| Jellyfin apps on phones/TVs | server address | watch |
| Bookmarks, Discord pinned links | `/about/`, `/clips/`, watch, live | all |
Not affected: Syncthing pairings (device IDs), MariaDB, stream tokens, the Gitea webhook (gateway IP), Authentik users/groups/policies.

## A. Renaming one subdomain (example: `watch.BASE` → `video.BASE`)

1. DNS: add `CNAME video.BASE → HOST`. Keep the old record until step 7.
2. Server, between streams: `./configure.py --full` → Enter keeps every value; type the new name at the
   "Jellyfin hostname" prompt; `y`. Caddy reloads (new block, old gone), Jellyfin is recreated with the new
   published URL. `curl -sI https://video.BASE/ | head -1` → 200/302 once the certificate is issued.
   (Only the *main* host touches `mediamtx.yml`; other hosts need no MediaMTX restart.)
3. Authentik: Applications → Providers → `Jellyfin` → Edit → redirect URI → the new host → Update.
4. Jellyfin: Dashboard → General → Branding → disclaimer form action → new host → Save.
   Dashboard → Plugins → Vanguard Metadata → Public URL → new host → Save.
5. If the *label* changed (`watch`→`video`), edit `about/index.html` (`sub('watch')` → `sub('video')`) — commit, push,
   `sudo vanguard-deploy pull`. (`.env APEX_REDIRECT` too if the bare domain pointed at it: `./configure.py --full`.)
6. Private window: `https://video.BASE/` → Discord → in. `https://HOST/about/` links to the new name.
7. Remove the old DNS record. Tell members with Jellyfin apps to update the server address.

Per-host extras when it is a different host:
- **auth**: Discord portal redirect; Authentik outpost `authentik_host` and the proxy provider's authentication URL;
  Jellyfin SSO plugin OID endpoint; Vanguard plugin Authentik URL; Gitea auth source discovery URL;
  `dock/index.html` + `about/index.html` if the label changed. Everyone re-logs in.
- **git**: Authentik Gitea provider redirect; `./registerGiteaRunner.sh`; server clone remote + `~/.ssh/config.vanguard`;
  dev remote; `switchToClone.sh` default.
- **live**, **bot**: only the compose env (automatic) and `about/index.html` if the label changed.
- **main (HOST)**: `mediamtx.yml` changes → `docker compose restart mediamtx` between streams; every streamer
  re-adds the dock URL, re-saves Settings (ingest host), and re-runs "Add band + clock source"; manual RTMP/SRT
  configs are re-copied from the dock; `deployLive.sh` default host.

## B. Changing the base domain (everything at once)

Plan a maintenance window: Caddy, Jellyfin, Gitea, the bot and MediaMTX all restart, and every member logs in again
(the Authentik session cookie is bound to the base domain).

1. DNS on the new domain: `A HOST2 → IP`, CNAMEs `auth`, `watch`, `git`, `bot`, `live` → `HOST2` (optional bare domain A).
   Verify they resolve before continuing. Leave the old domain's records in place for now.
2. Discord developer portal → OAuth2 → add redirect `https://auth.NEW/source/oauth/callback/discord/` (keep the old one until step 9).
3. Server, between streams: `./configure.py --full` → new main hostname; the five sub-hostnames default to the new
   base (Enter); bare domain; `y`. Then `docker compose restart mediamtx` (webrtcAdditionalHosts changed).
   All sites answer on the new names within a minute (certificates).
4. Authentik (log in at the NEW auth host with akadmin — Discord login is broken until step 5 is done):
   - Outposts → Embedded Outpost → `authentik_host: https://auth.NEW`
   - Providers → `Vanguard sites` → authentication URL `https://auth.NEW`, **cookie domain `NEW`**
   - Providers → `Jellyfin` → redirect `https://watch.NEW/sso/OID/redirect/authentik`
   - Providers → `Gitea` → redirect `https://git.NEW/user/oauth2/authentik/callback`
5. Private window: `https://auth.NEW/` → Discord login works (the redirect from step 2 is used).
6. Jellyfin: SSO plugin OID endpoint `https://auth.NEW/application/o/jellyfin/`; Branding disclaimer form action
   `https://watch.NEW/sso/OID/start/authentik`; Vanguard plugin Public URL + Authentik URL. Test the SSO start URL.
7. Gitea: auth source discovery URL `https://auth.NEW/application/o/gitea/.well-known/openid-configuration`;
   `./registerGiteaRunner.sh`; server: `cd ~/vanguard-stream && git remote set-url origin ssh://git@git.NEW:2222/techy/Media-Server-Setup.git`
   and edit `~/.ssh/config.vanguard` (Host line); dev box: `git remote set-url origin …`. Test `sudo vanguard-deploy pull`.
8. Repo defaults: `switchToClone.sh` (REPO_SSH), `deployLive.sh` (HOST) — commit, push, pull.
9. Streamers: re-add the dock at `https://HOST2/dock/`, re-save Settings, "Add band + clock source" again.
   Members: `https://HOST2/about/`; Jellyfin apps → new server address. Remove the old Discord redirect and the old DNS.

## Checklist after any change
    dev$ for h in HOST auth.BASE watch.BASE git.BASE live.BASE bot.BASE; do printf '%-26s ' $h; curl -s -o /dev/null -m 10 -w '%{http_code}\n' https://$h/; done
    https://HOST/whoami            → your identity (gate works on the new name)
    https://watch.BASE/sso/OID/start/authentik   → Jellyfin SSO round trip
    https://git.BASE/user/login    → "Sign in with authentik" round trip
    dock → Go Live → journalctl -u dumpd | grep mtx-auth   → allow publish
    live.BASE → a window appears for the test stream, chip "webrtc"