From 5037f5157a81b1b54749df0644b0f83ae626db2e Mon Sep 17 00:00:00 2001
From: Craig <3979063+craig8@users.noreply.github.com>
Date: Fri, 10 Jul 2026 11:00:10 -0700
Subject: [PATCH] docs: note that an absent systemrealm.cfg intentionally hangs
 startup

After the system-realm activation-order fix, SystemBasedRealm is a mandatory
Declarative Services dependency. When pnnl.goss.core.security.systemrealm.cfg
is absent the realm never publishes, the mandatory reference never binds, and
startup hangs with no broker. Document this fail-closed behavior in the
production deployment troubleshooting guide so operators read the hang as a
missing-config signal, not a platform bug.
---
 docs/PRODUCTION-DEPLOYMENT.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/PRODUCTION-DEPLOYMENT.md b/docs/PRODUCTION-DEPLOYMENT.md
index 8d4f03e2..66316b0d 100644
--- a/docs/PRODUCTION-DEPLOYMENT.md
+++ b/docs/PRODUCTION-DEPLOYMENT.md
@@ -692,6 +692,14 @@ openssl x509 -in /opt/goss/ssl/goss-server.crt -text -noout
 openssl s_client -connect localhost:61443
 ```
 
+#### 5. Platform Startup Hangs with No Broker
+
+If the platform hangs at startup with no error message and the broker does not initialize, the system realm configuration may be missing. Starting with PR #1882, the system-authenticating Shiro realm (SystemBasedRealm) is a mandatory Declarative Services dependency for platform startup, declared with ConfigurationPolicy.REQUIRE and configuration PID pnnl.goss.core.security.systemrealm.
+
+When the configuration file pnnl.goss.core.security.systemrealm.cfg is absent, the system realm never publishes as a service. The mandatory @Reference that gates the broker and SecurityManager never binds, causing the platform startup to hang indefinitely with no broker started. This is intentional fail-closed behavior: the system will not start an insecure broker.
+
+Remedy: ensure the configuration file pnnl.goss.core.security.systemrealm.cfg is present and properly mounted in the deployment environment. If the file is missing, copy it from the distribution bundle or recreate it with appropriate security settings for your deployment.
+
 ### Getting Support
 
 1. **Check logs**: `/opt/goss/logs/`