From 3d1eed6b65ddaa5652c8f5b18113d10db151d519 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Fri, 22 May 2026 20:19:24 +0200 Subject: [PATCH] docs(ui): make TLS extra hosts section answer "do I need this?" first MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previous text explained how the merge works but didn't give operators a clear signal for when to act. New structure leads with: - "When you need this": rarely; symptoms a user actually sees (presets reset, BoseApp offline) instead of a syslog string most users won't consult. - "How to tell": open the Health tab, look for speaker_marge_url; if clean, leave this empty. - "Manual path": only after the user has decided they need it. Adds a small, always-visible hint below the label that points to the Health tab — most operators won't expand the ⓘ panel. Co-Authored-By: Claude Sonnet 4.6 --- pkg/service/handlers/web/index.html | 41 ++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/pkg/service/handlers/web/index.html b/pkg/service/handlers/web/index.html index eae7b2e..e83974d 100644 --- a/pkg/service/handlers/web/index.html +++ b/pkg/service/handlers/web/index.html @@ -169,22 +169,39 @@ TLS extra hosts: ⓘ
- Additional DNS names or IPs the served TLS certificate - should cover. Speakers that talk to AfterTouch via a - hostname or IP not already in the cert's SAN list - reject the TLS handshake — typically symptom: + When you need this: rarely. The TLS + certificate already covers AfterTouch's configured + server URL, HTTPS URL, and the host's own name. Add + entries here only when a speaker can't reach + AfterTouch over TLS — typical symptoms include + presets resetting on reboot, the BoseApp showing + the speaker as offline, or CURLE_SSL_CACERT (60) in the speaker - syslog. The - speaker_marge_url health check on the - Health tab detects this and offers a one-click - QuickFix that appends the missing host here.
- Applying changes requires a service restart. - The TLS certificate is regenerated at startup from - the merged list of --server-url host, + syslog.
+ How to tell: open the + Health tab and look for + speaker_marge_url warnings. Each + warning names the host a speaker is pointing at; + clicking the Add <host> to TLS hosts + QuickFix fills this list for you. If that check is + clean, this list can stay empty.
+ Manual path: add one host per line + and save. The TLS certificate is regenerated at + startup from the merged list of + --server-url host, --https-server-url host, the system hostname, any --tls-extra-host / TLS_EXTRA_HOST CLI/env values, and the - hosts persisted below. + hosts persisted here. CLI/env wins over persisted + on overlap.
+ Applying changes requires a service + restart. +
+
+ Usually empty. Add a host here only if the + Health tab + flags a speaker_marge_url warning — or use + the one-click QuickFix on that warning to fill it for you.