Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Distinguish licence activation from private-runtime recovery

pulse-triage[bot]2fef255fe555
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 4b4bda0301..a8b0ad1ad1 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -105,6 +105,10 @@ Pro and Cloud unlock **hands-on Patrol modes, issue investigation, governed fixe
Example output includes trend-based capacity warnings, backup regressions, Kubernetes cluster analysis, and correlated container failures that simple threshold alerts miss.
See [Pulse Intelligence](AI.md), [Plans and entitlements](PULSE_PRO.md), and <https://pulserelay.pro>.
+An accepted licence does not install the private Pro runtime. If a paid plan is
+active but its features remain unavailable, use the [licence recovery distinctions](PULSE_PRO.md#activation-succeeds-but-pro-features-are-unavailable)
+before applying the key again, clearing it or changing the installation.
+
### What happens to Pulse Mobile and Relay?
Pulse Mobile and Relay retire on **31 March 2027**. Existing paired phones keep
diff --git a/docs/PULSE_PRO.md b/docs/PULSE_PRO.md
index 809f15f137..65eb604545 100644
--- a/docs/PULSE_PRO.md
+++ b/docs/PULSE_PRO.md
@@ -229,7 +229,46 @@ Pulse plan upgrades are activated locally with a license key.
- Pulse v6 prefers v6 activation keys, but it can migrate valid Pulse v5 Pro or Lifetime JWT-style licenses into the v6 activation model.
- If a v5 license is already persisted on disk during upgrade and no v6 activation state exists yet, Pulse will try to auto-exchange it on startup.
- If you are activating manually in v6, paste the v6 activation key shown on the hosted checkout success page. A backup copy is also sent by email. You can also paste a valid v5 Pro or Lifetime license key and Pulse will try to exchange it automatically.
-- If the exchange cannot complete, retry from the v6 license panel or use the self-serve retrieval flow to fetch the current v6 activation key.
+- If activation or migration fails, use the [recovery distinctions below](#activation-succeeds-but-pro-features-are-unavailable) before applying the key again. Self-serve retrieval is for recovering a key, not installing the Pro runtime.
+
+### Activation succeeds but Pro features are unavailable
+
+**An accepted key and an installed Pro runtime are separate requirements.**
+Open **Plans & Billing → Plan** on the intended Pulse instance and organisation.
+Read the current plan, runtime notice and specific error before changing anything:
+
+- **The plan is active, but “Pro runtime missing” or “Pulse Pro runtime required”
+ is shown:** public GitHub archives and the public `rcourtman/pulse` image are
+ Community builds. They can accept a licence, but applying it again does not
+ install the private Pro runtime. Use **Open Pulse Pro downloads**, or open
+ <https://pulserelay.pro/download.html> yourself and enter the existing activation
+ key only in that trusted page. Choose the private image or archive for your
+ deployment; follow [existing-installation preparation](AUTO_UPDATE.md#manual-update-methods)
+ and preserve the configuration, data, keys and service identity. Do not replace
+ an existing private image with the public image or buy another licence to fix
+ this mismatch.
+- **The key is rejected, expired or cannot be verified:** retain the specific
+ message. A key-format error, an unavailable licence service and a build without
+ a validation key need different remedies; none is proof that your purchase is
+ missing. After correcting the named cause, expand **License recovery → Manual
+ key recovery** and use **Apply key** for the intended key correction or
+ supported legacy migration. Do not use **Clear key** as a diagnostic
+ reset, delete licence files or change unrelated authentication settings.
+- **Plan status cannot be loaded:** the read is unavailable, not proof that the
+ licence was removed or the subscription ended. Keep the original error and
+ time rather than repeatedly applying a key, clearing it or starting checkout.
+
+After a deliberate runtime change, check the running edition, loaded plan and
+the particular capability you needed. A successful download, activation banner
+or server restart alone does not establish that the private runtime is running
+or that monitoring recovered. Licence activation does not upgrade installed agents.
+
+Keep activation keys, licence files, account links, session cookies and full
+configuration private. Do not paste them into shell commands, URLs or public
+reports. For a technical report, use the running version, deployment type,
+displayed runtime/plan and locally redacted error; unknown is valid. Use the
+private account/support route for purchase, payment or licence-ownership disputes,
+not a public issue containing account evidence.
### Feature Status API
diff --git a/frontend-modern/public/docs/FAQ.md b/frontend-modern/public/docs/FAQ.md
index 4b4bda0301..a8b0ad1ad1 100644
--- a/frontend-modern/public/docs/FAQ.md
+++ b/frontend-modern/public/docs/FAQ.md
@@ -105,6 +105,10 @@ Pro and Cloud unlock **hands-on Patrol modes, issue investigation, governed fixe
Example output includes trend-based capacity warnings, backup regressions, Kubernetes cluster analysis, and correlated container failures that simple threshold alerts miss.
See [Pulse Intelligence](AI.md), [Plans and entitlements](PULSE_PRO.md), and <https://pulserelay.pro>.
+An accepted licence does not install the private Pro runtime. If a paid plan is
+active but its features remain unavailable, use the [licence recovery distinctions](PULSE_PRO.md#activation-succeeds-but-pro-features-are-unavailable)
+before applying the key again, clearing it or changing the installation.
+
### What happens to Pulse Mobile and Relay?
Pulse Mobile and Relay retire on **31 March 2027**. Existing paired phones keep
diff --git a/frontend-modern/public/docs/PULSE_PRO.md b/frontend-modern/public/docs/PULSE_PRO.md
index 809f15f137..65eb604545 100644
--- a/frontend-modern/public/docs/PULSE_PRO.md
+++ b/frontend-modern/public/docs/PULSE_PRO.md
@@ -229,7 +229,46 @@ Pulse plan upgrades are activated locally with a license key.
- Pulse v6 prefers v6 activation keys, but it can migrate valid Pulse v5 Pro or Lifetime JWT-style licenses into the v6 activation model.
- If a v5 license is already persisted on disk during upgrade and no v6 activation state exists yet, Pulse will try to auto-exchange it on startup.
- If you are activating manually in v6, paste the v6 activation key shown on the hosted checkout success page. A backup copy is also sent by email. You can also paste a valid v5 Pro or Lifetime license key and Pulse will try to exchange it automatically.
-- If the exchange cannot complete, retry from the v6 license panel or use the self-serve retrieval flow to fetch the current v6 activation key.
+- If activation or migration fails, use the [recovery distinctions below](#activation-succeeds-but-pro-features-are-unavailable) before applying the key again. Self-serve retrieval is for recovering a key, not installing the Pro runtime.
+
+### Activation succeeds but Pro features are unavailable
+
+**An accepted key and an installed Pro runtime are separate requirements.**
+Open **Plans & Billing → Plan** on the intended Pulse instance and organisation.
+Read the current plan, runtime notice and specific error before changing anything:
+
+- **The plan is active, but “Pro runtime missing” or “Pulse Pro runtime required”
+ is shown:** public GitHub archives and the public `rcourtman/pulse` image are
+ Community builds. They can accept a licence, but applying it again does not
+ install the private Pro runtime. Use **Open Pulse Pro downloads**, or open
+ <https://pulserelay.pro/download.html> yourself and enter the existing activation
+ key only in that trusted page. Choose the private image or archive for your
+ deployment; follow [existing-installation preparation](AUTO_UPDATE.md#manual-update-methods)
+ and preserve the configuration, data, keys and service identity. Do not replace
+ an existing private image with the public image or buy another licence to fix
+ this mismatch.
+- **The key is rejected, expired or cannot be verified:** retain the specific
+ message. A key-format error, an unavailable licence service and a build without
+ a validation key need different remedies; none is proof that your purchase is
+ missing. After correcting the named cause, expand **License recovery → Manual
+ key recovery** and use **Apply key** for the intended key correction or
+ supported legacy migration. Do not use **Clear key** as a diagnostic
+ reset, delete licence files or change unrelated authentication settings.
+- **Plan status cannot be loaded:** the read is unavailable, not proof that the
+ licence was removed or the subscription ended. Keep the original error and
+ time rather than repeatedly applying a key, clearing it or starting checkout.
+
+After a deliberate runtime change, check the running edition, loaded plan and
+the particular capability you needed. A successful download, activation banner
+or server restart alone does not establish that the private runtime is running
+or that monitoring recovered. Licence activation does not upgrade installed agents.
+
+Keep activation keys, licence files, account links, session cookies and full
+configuration private. Do not paste them into shell commands, URLs or public
+reports. For a technical report, use the running version, deployment type,
+displayed runtime/plan and locally redacted error; unknown is valid. Use the
+private account/support route for purchase, payment or licence-ownership disputes,
+not a public issue containing account evidence.
### Feature Status API
diff --git a/scripts/tests/test_license_recovery_docs.py b/scripts/tests/test_license_recovery_docs.py
new file mode 100644
index 0000000000..0782df5613
--- /dev/null
+++ b/scripts/tests/test_license_recovery_docs.py
@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Keep licence recovery help distinct from runtime installation and account proof.
+
+This checks shipped guidance against existing controls, not an activation,
+private download or installed-runtime recovery.
+"""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+HEADING = "### Activation succeeds but Pro features are unavailable"
+FRAGMENT = "PULSE_PRO.md#activation-succeeds-but-pro-features-are-unavailable"
+
+
+def section(text):
+ return " ".join(text.split(HEADING + "\n", 1)[1].split("\n### ", 1)[0].split())
+
+
+class LicenseRecoveryDocsTest(unittest.TestCase):
+ def test_shipped_guides_match_and_short_answer_reaches_recovery(self):
+ for name in ("PULSE_PRO", "FAQ"):
+ with self.subTest(guide=name):
+ source = (ROOT / f"docs/{name}.md").read_bytes()
+ self.assertEqual(source, (ROOT / f"frontend-modern/public/docs/{name}.md").read_bytes())
+ self.assertIn(FRAGMENT, (ROOT / "docs/FAQ.md").read_text())
+
+ def test_active_key_is_not_a_private_runtime_install(self):
+ text = section((ROOT / "docs/PULSE_PRO.md").read_text())
+ for phrase in (
+ "accepted key and an installed Pro runtime are separate requirements",
+ "intended Pulse instance and organisation",
+ "applying it again does not install the private Pro runtime",
+ "https://pulserelay.pro/download.html",
+ "AUTO_UPDATE.md#manual-update-methods",
+ "preserve the configuration, data, keys and service identity",
+ "Do not replace an existing private image with the public image",
+ "buy another licence",
+ "check the running edition, loaded plan",
+ "does not upgrade installed agents",
+ ):
+ with self.subTest(phrase=phrase):
+ self.assertIn(phrase, text)
+ presentation = (ROOT / "frontend-modern/src/utils/licensePresentation.ts").read_text()
+ self.assertIn("Pro runtime missing", presentation)
+ self.assertIn("They can accept the license, but Pro-only runtime hooks", presentation)
+ self.assertIn("privateRuntimeAction:", presentation)
+
+ def test_failed_reads_and_rejected_keys_do_not_prompt_destructive_reset(self):
+ text = section((ROOT / "docs/PULSE_PRO.md").read_text())
+ for phrase in (
+ "key-format error, an unavailable licence service and a build without a validation key",
+ "Do not use **Clear key** as a diagnostic reset",
+ "delete licence files",
+ "read is unavailable, not proof that the licence was removed",
+ "original error and time",
+ "session cookies and full configuration private",
+ "Do not paste them into shell commands, URLs or public reports",
+ "locally redacted error; unknown is valid",
+ "private account/support route",
+ ):
+ with self.subTest(phrase=phrase):
+ self.assertIn(phrase, text)
+ controls = (ROOT / "frontend-modern/src/utils/licensePresentation.ts").read_text()
+ for label in ("Manual key recovery", "Apply key", "Clear key"):
+ self.assertIn(label, controls)
+ handlers = (ROOT / "internal/api/licensing_handlers.go").read_text()
+ self.assertIn("This Pulse build cannot verify Pro licenses", handlers)
+ self.assertIn("The license server is temporarily unavailable", handlers)
+
+
+if __name__ == "__main__":
+ unittest.main()