From 275d5026395c6079a8bc631c8be73332b5fd6f31 Mon Sep 17 00:00:00 2001
From: atlas <atlas@pr1ma.darkest.space>
Date: Wed, 12 Aug 2026 10:08:34 +0200
Subject: [PATCH] feat(3189): the sso vhost serves a themed page instead of a
 bare 502
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A dead authelia upstream almost always means "no users yet" — authelia
treats an empty user store as a fatal startup error, so an enabled but
unbootstrapped swarm crash-loops behind a vhost that is working
perfectly. nginx's default 502 says the opposite: it points at the
proxy, which is the one component that is fine.

Adds `ssoUnavailable` to the shared error-page set and wires it on the
authelia vhost the same way the per-agent blocks wire
`__hive_agent_unreachable`: `proxy_intercept_errors on` plus an internal
location serving the static page.

The page leads with the bootstrap command rather than burying it under
an explanation, and names the container journal as the fallback for the
cases where users are not the problem. Same Catppuccin template as its
siblings, so this costs no new styling.
---
 nix/host-modules/hive-gateway/error-pages.nix | 18 ++++++++++++++++++
 nix/host-modules/hive-gateway/vhosts.nix      | 11 +++++++++++
 2 files changed, 29 insertions(+)

diff --git a/nix/host-modules/hive-gateway/error-pages.nix b/nix/host-modules/hive-gateway/error-pages.nix
index 3285632c..f1ad62e9 100644
--- a/nix/host-modules/hive-gateway/error-pages.nix
+++ b/nix/host-modules/hive-gateway/error-pages.nix
@@ -56,6 +56,24 @@ in
     '';
   };
 
+  # Shown when the authelia vhost's upstream refuses the connection.
+  # Leads with the bootstrap because that is overwhelmingly the cause:
+  # authelia treats an empty user store as a FATAL startup error, so an
+  # enabled-but-unbootstrapped swarm crash-loops behind a vhost that is
+  # working perfectly, and the raw 502 points at the proxy instead.
+  ssoUnavailable = mkPage {
+    name = "sso-unavailable";
+    title = "sso unavailable";
+    accent = "#f9e2af";
+    body = ''
+      <p>The swarm's identity provider isn't answering. The gateway is fine — nothing is listening behind it.</p>
+      <p class="hint">Most likely: <strong>no users exist yet.</strong> Authelia refuses to start with an empty user store, so it never finishes booting. Add the first account on the host running it:</p>
+      <pre>swarmctl user add &lt;username&gt; \
+      --display-name &lt;Name&gt; --email &lt;addr&gt; --group admins</pre>
+      <p class="hint">Otherwise check the container: <code>journalctl -M swarm-authelia -u authelia-swarm</code>. This page recovers on reload once the provider is up.</p>
+    '';
+  };
+
   unauthorized = mkPage {
     name = "unauthorized";
     title = "unauthorized";
diff --git a/nix/host-modules/hive-gateway/vhosts.nix b/nix/host-modules/hive-gateway/vhosts.nix
index 20d9c97d..297c724f 100644
--- a/nix/host-modules/hive-gateway/vhosts.nix
+++ b/nix/host-modules/hive-gateway/vhosts.nix
@@ -155,6 +155,17 @@ let
           proxy_set_header X-Forwarded-Host $host;
           proxy_set_header X-Forwarded-Uri $request_uri;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+          # A dead upstream here means "not bootstrapped" far more often
+          # than "misconfigured proxy", and a bare 502 says the opposite.
+          proxy_intercept_errors on;
+          error_page 502 503 504 = /__hive_sso_unavailable;
+        '';
+      };
+      locations."= /__hive_sso_unavailable" = {
+        extraConfig = ''
+          internal;
+          alias ${errorPages.ssoUnavailable};
+          default_type text/html;
         '';
       };
     };