Update documentation for port-based routing

[mairas]

Summary

• Replace all subdomain-based routing references (grafana.halos.local) with port-based routing (dedicated HTTPS ports 4430–4450) and path redirects (halos.local/grafana/)
• Document port registry, HALOS_EXTERNAL_PORT env var, and path redirect mechanism
• Update Authelia URL from auth.halos.local to halos.local/sso/
• Update TLS docs: single-hostname cert replaces wildcard *.halos.local
• Remove mDNS publisher reference page (the service no longer advertises per-app subdomains)
• Fix all app URLs across 21 files

Test plan

• mkdocs serve builds without errors or broken links
• grep -r "subdomain" docs/ returns only the intentional historical reference in networking.md
• grep -rE "\w+\.halos\.local" docs/ returns only the same historical reference
• All URL tables use halos.local/<app-id>/ or halos.local:<port> format

🤖 Generated with Claude Code

[mairas]

Adversarial Review

Gut Reaction

A thorough and mostly consistent migration across 21 files, but several factual inconsistencies, missed files, and one numbering bug slipped through.

Critical Issues

1. Numbering gap in package-system.md (step 4 jumps to 6)

• Location: docs/architecture/package-system.md:99-100
• Problem: After removing step 4 (mDNS labels) and renumbering step 5 to 4, step 6 ("Builds the .deb package") was not renumbered to 5. The list reads: 1, 2, 3, 4, 6.
• Risk: Looks like a sloppy omission to readers. They may wonder if step 5 is missing or intentionally removed.
• Suggestion: Renumber step 6 to step 5.

2. homarr.url uses redirect URL instead of direct port URL

• Location: docs/user-guide/dashboard.md:19
• Problem: The example shows homarr.url: "https://halos.local/my-app/" — but elsewhere the docs explain that path URLs are 302 redirects to the app's dedicated port. If Homarr tiles use the redirect URL, clicking a tile triggers a redirect before reaching the app. Is this the actual behavior, or should homarr.url point to the direct port URL (e.g., https://halos.local:4431/)? If redirect is intentional, the docs should explain why (e.g., "redirect URLs are used so port numbers don't leak into the UI"). If not, this is a documentation bug.
• Risk: Developers packaging apps will set wrong URLs in labels if the example is wrong.
• Suggestion: Clarify whether this is the actual generated label value and, if so, explain the redirect behavior.

3. Cockpit lost SSO — behavioral change not called out

• Location: docs/user-guide/system-management.md:12-13
• Problem: Previously, Cockpit was accessible via cockpit.halos.local through Traefik with Authelia SSO authentication. Now it is just a redirect to port 9090 with system credentials only. This is a security/UX regression (users must maintain separate credentials for Cockpit) that the docs silently paper over. The old table had two access methods with two auth mechanisms; the new table has two methods that both use the same auth (system credentials).
• Risk: Users who relied on SSO for Cockpit access will be confused. This is an architectural change that deserves explicit mention — not just a URL update.
• Suggestion: Either document that Cockpit SSO was removed and explain why, or if Cockpit is still proxied through Traefik on a dedicated port with SSO, document that instead.

Major Concerns

4. Stale references in unchanged files

• Location: docs/developer-guide/contributing.md:23

• Problem: Still lists "mDNS publisher: halos-mdns-publisher" as a place to file issues, with a link to the repo. If the mDNS publisher is no longer a core component (its reference page was deleted), this is stale.

• Risk: Contributors will file issues against a component that may be deprecated.

• Suggestion: Remove or update this entry.

• Location: docs/developer-guide/workspace-setup.md:45, 67, 92

• Problem: Three stale mDNS publisher references survive: the build tools table lists "mDNS publisher" with Rust, the hook installation section shows cd ../halos-mdns-publisher, and the directory tree lists it. The directory tree line was updated to say "mDNS hostname publisher" (good), but the other two were not touched.

• Risk: Developers following setup instructions will try to clone and set up hooks for a component that may no longer be relevant.

• Suggestion: Either keep these (if halos-mdns-publisher still exists as a hostname-only publisher) and explain its reduced role, or remove them if the component is fully deprecated.

5. Authelia ForwardAuth URL change needs verification

• Location: docs/architecture/reverse-proxy.md:150
• Problem: The ForwardAuth address changed from http://authelia:9091/api/authz/forward-auth to http://authelia:9091/sso/api/authz/forward-auth. This implies Authelia itself is now served under a /sso path prefix. Is this actually true in the deployed Authelia configuration? If Authelia is mounted at /sso/ on port 443 but still listens internally on port 9091 at the root path, then the internal ForwardAuth address should NOT include /sso (that prefix is only for the external Traefik route, not the internal container-to-container communication).
• Risk: If this is wrong, ForwardAuth will 404 and authentication will be completely broken for all apps.
• Suggestion: Verify this against the actual docker-compose.yml / Authelia configuration in halos-core-containers.

6. Self-signed cert claim "accept once" is misleading

• Location: docs/getting-started/first-boot.md:63-64, docs/user-guide/troubleshooting.md:30
• Problem: The docs claim "you only need to accept the warning once" because all ports share the same hostname. This is technically true for the certificate validation, but browsers treat different ports as different origins. Most browsers will show the certificate warning again for each new port visited (Chrome, for example, stores cert exceptions per host:port). Only after the user imports the CA cert into their trust store would the single-accept claim be accurate.
• Risk: Users will be confused when they still see cert warnings on every new app port, contradicting the documentation.
• Suggestion: Either explain how to import the self-signed CA cert into the trust store (the only way to truly get "accept once" behavior), or be honest: "you'll see a warning the first time you access each app's port — accept it and it won't appear again for that port."

Minor Issues

7. Signal K path uses signalk-server not signalk

• Location: docs/user-guide/marine-apps.md:19, docs/reference/marine-containers.md:18
• Problem: The URL is halos.local/signalk-server/ while all other apps use short names (grafana, avnav, influxdb). This is presumably because the app-id is signalk-server, but it's inconsistent with user expectations. Not a docs bug per se, but worth noting — the old subdomain was just signalk.
• Suggestion: If this is intentional, no change needed. If the app-id can be signalk, that would be more user-friendly.

8. Port 9090 listed in Traefik port range but is not Traefik's

• Location: docs/architecture/reverse-proxy.md:13
• Problem: "Ports 80, 443, 9090, and 4430-4450 are exposed to the network" — but 9090 is Cockpit's port, not Traefik's. Listing it alongside Traefik's ports in the "Why a Reverse Proxy?" section implies Traefik manages it.
• Suggestion: Either remove 9090 from this list (it's not a reverse proxy concern) or clarify: "Ports 80, 443, and 4430-4450 are exposed via Traefik; Cockpit independently exposes port 9090."

9. Em-dash normalization is inconsistent with change scope

• Multiple locations: -- changed to — in touched files
• Problem: While individually correct, these typography changes are mixed into the routing migration commits. They make the diff noisier without being related to the PR's purpose.
• Suggestion: Not worth reverting, but avoid mixing style fixes into semantic PRs in the future.

10. Port range of 21 ports (4430-4450) may be limiting

• Location: docs/architecture/reverse-proxy.md:36
• Problem: If a user installs more than 21 apps, the port registry is full. The docs don't mention what happens in this case.
• Suggestion: Add a brief note about the limit and what happens when it's reached.

Questions

1. Is halos-mdns-publisher still a thing? The reference page was deleted and most references removed, but the workspace-setup still lists it, and contributing.md still links to it. The workspace-setup even updates its description to "mDNS hostname publisher" — suggesting it still exists but with reduced scope (just advertising the base hostname). If so, should it still have a reference page (just a shorter one)?

2. What happens to existing bookmarks? Users upgrading from subdomain-based to port-based routing will have bookmarks to grafana.halos.local etc. These will completely break. Should there be a migration/upgrade note?

3. Does the path redirect require Traefik to be running? If Traefik is down, halos.local/grafana/ won't work. But can users still access apps directly via halos.local:<port>? If so, how do they know the port numbers? This seems like important troubleshooting information that's missing.

4. Are 302 redirects the right choice? 302 means "temporary" — browsers won't cache them and will hit the redirect on every page load. If port assignments are stable (which the docs claim), should these be 301 (permanent) redirects so browsers cache them?

What's Actually Good

• The sweep across 21 files is thorough — the grep verification in the test plan is smart and the results confirm only one intentional historical reference survives.
• Commit structure is clean: architecture first, then reference, then developer guide, then user guide, then stragglers. Each commit has a clear scope.
• The new HALOS_EXTERNAL_PORT documentation and port registry concept are well-explained.
• Removing the mDNS publisher page and nav entry is correct — don't leave zombie pages.
• The networking.md change preserves historical context ("previously... removed because Windows doesn't support multi-label mDNS") rather than pretending subdomains never existed.

[mairas]

Review Response

Summary

3 of 10 findings warranted fixes; the rest are either false positives, cosmetic, or out of scope. Pushed fixes in 3cc7f6a.

Accepted

• Finding 1: Numbering gap in package-system.md — Steps went 4→6 after removing the mDNS step. Renumbered to 4→5.
• Finding 6: "Accept cert once" is misleading — Valid point. Browsers store cert exceptions per host:port, so with port-based routing users will see a cert warning on each new port. Updated first-boot.md and troubleshooting.md to accurately describe this behavior.

Rejected

• Finding 2: homarr.url uses redirect URL — The redirect URL (halos.local/my-app/) is what users see and click. It's the correct URL for a dashboard tile. The redirect then takes them to the port. This is intentional.

• Finding 3: Cockpit SSO silently removed — The table accurately describes the new behavior. Cockpit is no longer proxied through Traefik; it gets a path redirect to port 9090. This is the whole point of the port-based routing migration. The PR diff makes this change visible.

• Finding 4: Stale mDNS references in contributing.md and workspace-setup.md — These are NOT stale references. contributing.md:23 lists halos-mdns-publisher as a repo for issue reporting. workspace-setup.md:45 and :92 reference it as a repo in the workspace. The halos-mdns-publisher repo still exists and publishes the halos.local hostname — that hasn't changed. The migration was from subdomain-based routing to port-based routing; mDNS hostname publishing is unrelated.

• Finding 5: Authelia ForwardAuth URL with /sso prefix — The /sso prefix in http://authelia:9091/sso/api/authz/forward-auth is correct. Authelia is configured with /sso as its path prefix (it serves the SSO portal at halos.local/sso/), and the internal authz endpoint uses the same prefix.

• Finding 7: Signal K uses signalk-server path while other apps use short names — This is how the app is defined (its app_id). Not a documentation error.

• Finding 8: Port 9090 listed alongside Traefik ports — Checked context at reverse-proxy.md:13. The line reads "Ports 80, 443, 9090, and 4430–4450 are exposed to the network" — it's listing all externally-exposed ports, not claiming 9090 is a Traefik port. Cockpit on 9090 is then separately described in the routing table and the "Cockpit Integration" section.

• Finding 9: Em-dash normalization — Cosmetic. No action.

• Finding 10: No docs on port range exhaustion — Out of scope for this PR. The port range 4430–4450 supports 21 apps which is well beyond typical usage. Can be documented later if needed.