Clarify setup wizard ingress certificate guidance

archivebox/templates/core/setup_wizard.html

@@ -50,8 +50,8 @@
       <div class="abx-question-options" id="archivebox-setup-tls-options">
         <label class="abx-question-option"><input type="radio" name="archivebox-tls-mode" value="localhost"> <span><b>⭐ Localhost</b><small>No setup needed. HTTPS is not required for local access; all replay features remain available.</small></span></label>
         <label class="abx-question-option"><input type="radio" name="archivebox-tls-mode" value="none"> <span><b>⚠️ No separate ingress service / SSL termination</b><small>Access ArchiveBox directly without an ingress service like Cloudflare/AWS/Nginx/Caddy/Traefik in front. In-browser WARC viewing will be disabled unless using <code>localhost</code> or HTTPS.</small></span></label>
-        <label class="abx-question-option"><input type="radio" name="archivebox-tls-mode" value="single"> <span><b>⚠️ Single-domain HTTPS certificate</b><small>One certificate from Nginx + Let's Encrypt, Caddy, Traefik, Cloudflare, Tailscale, or another ingress provider. This mode is not allowed unless also using Single-domain DNS.</small></span></label>
-        <label class="abx-question-option"><input type="radio" name="archivebox-tls-mode" value="wildcard"> <span><b>⭐ Wildcard TLS</b><small>A <code>*.example.com</code> certificate from Let's Encrypt, Cloudflare, or another wildcard-capable provider. Ideal for public isolated-subdomain servers.</small></span></label>
+        <label class="abx-question-option"><input type="radio" name="archivebox-tls-mode" value="single"> <span><b>⚠️ Single-domain HTTPS certificate</b><small>Configure one certificate for the <code>BASE_URL</code> hostname in Cloudflare, Nginx Proxy Manager, Caddy, Traefik, Tailscale, or your platform's ingress UI, then proxy it to ArchiveBox on port <code>8000</code>. This mode is not allowed unless also using Single-domain DNS.</small></span></label>
+        <label class="abx-question-option"><input type="radio" name="archivebox-tls-mode" value="wildcard"> <span><b>⭐ Wildcard TLS</b><small>Configure one certificate covering both the <code>BASE_URL</code> hostname and <code>*.BASE_URL</code>, normally through DNS-01. Never enable on-demand TLS or request individual certificates for snapshot subdomains.</small></span></label>
       </div>
       <div class="abx-question-status" id="archivebox-setup-tls-status">Choose how HTTPS will reach ArchiveBox.</div>
     </fieldset>

archivebox/templates/static/setup_wizard.js

@@ -229,7 +229,7 @@
     var dnsMode = selectedValue(dnsInputs);
     var tlsMode = selectedValue(tlsInputs);
     var desiredScheme = tlsMode === 'wildcard' || tlsMode === 'single' ? 'https://' : 'http://';
-    var exampleBaseHost = 'archivebox.example.com';
+    var exampleBaseHost = currentPreview ? currentPreview.parsed.hostname : 'archivebox.example.com';
     var exampleWildcardHost = '*.' + exampleBaseHost;
     var exampleBaseUrl = desiredScheme + exampleBaseHost;
     var exampleWildcardUrl = desiredScheme + exampleWildcardHost;
@@ -253,9 +253,9 @@
     document.getElementById('archivebox-setup-tls-status').textContent = tlsMode === 'localhost'
       ? '❌ Visit ' + localhostAdminUrl + ' from this machine to continue setup. No certificate is needed.'
       : (tlsMode === 'wildcard'
-        ? '❌ Configure your SSL ingress service in front of this ArchiveBox server with a browser-trusted certificate covering ' + exampleBaseHost + ' and ' + exampleWildcardHost + '. Visit ' + exampleAdminUrl + ' to continue setup.'
+        ? '❌ In your ingress provider, proxy to ArchiveBox on port 8000 and configure one browser-trusted certificate covering ' + exampleBaseHost + ' and ' + exampleWildcardHost + ', normally through DNS-01. Never enable on-demand TLS or request individual snapshot certificates. Visit ' + exampleAdminUrl + ' to continue setup.'
         : (tlsMode === 'single'
-          ? '❌ Configure your SSL ingress service in front of this ArchiveBox server with a browser-trusted certificate for ' + exampleBaseHost + '. Visit ' + exampleAdminUrl + ' to continue setup.'
+          ? '❌ In your ingress provider, proxy to ArchiveBox on port 8000 and configure one browser-trusted certificate for ' + exampleBaseHost + '. Visit ' + exampleAdminUrl + ' to continue setup.'
           : (tlsMode === 'none'
             ? '❌ Expose this ArchiveBox server directly over HTTP without a separate ingress or SSL termination service. Visit ' + exampleAdminUrl + ' to continue setup. In-browser WARC viewing will remain disabled unless browsing through localhost or HTTPS.'
             : '❌ Choose an ingress and TLS mode. Your choice will not be changed automatically.')));

archivebox/tests/test_server_security_browser.py

@@ -736,6 +736,9 @@ def test_unconfigured_public_host_superuser_can_reach_setup_wizard(tmp_path: Pat
     assert "mkdir -p /etc/traefik" in traefik_entrypoint
     assert traefik_entrypoint.index("mkdir -p /etc/traefik") < traefik_entrypoint.index("> /etc/traefik/dynamic.yml")
     assert "--entrypoints.websecure.http.tls=true" in traefik_entrypoint
+    assert '--entrypoints.websecure.http.tls.domains[0].sans="*.$$DOMAIN"' in traefik_entrypoint
+    assert "on-demand" not in traefik_entrypoint.lower()
+    assert "ondemand" not in traefik_entrypoint.lower()
 
 
 def _run_wacz_preview_probe(

archivebox/tests/test_ui_admin_config_widget.py

@@ -153,6 +153,8 @@ def test_unconfigured_superuser_banner_uses_browser_assisted_setup_wizard():
     assert "JavaScript still runs during capture" in html
     assert "will not replay JavaScript unless wildcard DNS is used" in html
     assert "Wildcard TLS" in html
+    assert "Never enable on-demand TLS or request individual certificates for snapshot subdomains." in html
+    assert "Cloudflare, Nginx Proxy Manager, Caddy, Traefik, Tailscale" in html
     assert "How will HTTPS traffic reach this ArchiveBox server?" in html
     assert "This mode is not allowed unless also using Single-domain DNS." in html
     assert "No separate ingress service / SSL termination" in html
@@ -205,6 +207,7 @@ def test_setup_wizard_assets_enforce_selection_and_access_requirements():
     assert "archive intranet URLs" in SETUP_WIZARD_JS
     assert "tlsMode === 'single' && dnsMode !== 'single'" in SETUP_WIZARD_JS
     assert "Single-domain HTTPS is only allowed with Single-domain DNS." in SETUP_WIZARD_JS
+    assert "Never enable on-demand TLS or request individual snapshot certificates." in SETUP_WIZARD_JS
     assert "expectedBrowserOrigin: usesSubdomains ? adminOrigin : parsed.origin" in SETUP_WIZARD_JS
     assert "Waiting for a matching browser URL and valid setup options" in SETUP_WIZARD_JS
     assert "Finish the selected DNS, ingress, and TLS setup" in SETUP_WIZARD_JS

docs/Docker.md

@@ -173,12 +173,14 @@ services:
 
 You can also specify an env file via CLI when running compose using `docker compose --env-file=/path/to/config.env ...` although you must specify the variables in the `environment:` section that you want to have passed down to the ArchiveBox container from the passed env file.
 
-If you want to access your archive server with HTTPS, the bundled `docker-compose.yml` includes two opt-in ingress profiles:
+For public HTTPS, start the default stack with `docker compose up -d`, open the admin UI on port `8000`, and follow the first-run wizard. It gives the DNS, upstream, and certificate settings to enter in Cloudflare, Nginx Proxy Manager, Caddy, Traefik, Tailscale, or your hosting platform's ingress UI, then verifies the public URLs before saving `BASE_URL` and `SERVER_SECURITY_MODE`.
 
-- `COMPOSE_PROFILES=https` runs Traefik in front of ArchiveBox for HTTPS/TLS, with optional wildcard certificates via DNS-01.
-- `COMPOSE_PROFILES=tunnel` runs a Cloudflare Tunnel for deployments without a public IP.
+Use exactly one of these certificate layouts:
 
-Set `ARCHIVEBOX_INGRESS_BASE_URL=https://archive.example.com` and `ARCHIVEBOX_PORT=127.0.0.1:8000` in the `.env` file next to `docker-compose.yml`, then follow the inline comments in the compose file for the profile you choose. Log in through the resulting public admin URL and the first-run wizard will verify the DNS/TLS routes before saving `BASE_URL` and `SERVER_SECURITY_MODE`. The localhost port binding prevents direct HTTP access from bypassing the public HTTPS ingress. You can still bring your own reverse proxy such as Nginx or Caddy in front of `http://127.0.0.1:8000`; [`etc/nginx.conf`](https://github.com/ArchiveBox/ArchiveBox/blob/dev/etc/nginx.conf) remains a standalone example.
+- **Single-domain mode:** one certificate for the `BASE_URL` hostname, proxied to ArchiveBox port `8000`.
+- **Isolated-subdomain mode:** one certificate covering both the `BASE_URL` hostname and `*.BASE_URL`, normally obtained through DNS-01.
+
+Never enable on-demand TLS or request individual certificates for `snap-*` hostnames. The bundled Compose file also contains opt-in Cloudflare Tunnel and Traefik examples for users who prefer them; they follow the same certificate rules.
 
 <br/>