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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Keep Cloud migration within configuration-transfer limits
pulse-triage[bot]4662cafef681
diff --git a/docs/CLOUD.md b/docs/CLOUD.mdindex 74b0cacbc5..613e3734b1 100644--- a/docs/CLOUD.md+++ b/docs/CLOUD.md@@ -75,7 +75,9 @@ Relay is enabled by default on Cloud instances. Open **Settings → Pulse Mobile- Your monitoring data runs in an **isolated container** — no shared databases.- Data is stored encrypted at rest.- Backups are automated and encrypted.-- You can **export** your configuration at any time via **Settings → System → Recovery** and migrate to self-hosted if needed.+- **Create Backup** in **Settings → System → Recovery** downloads an encrypted+ configuration export, not a complete copy of the hosted installation. Check+ the [migration scope](#migrating-tofrom-cloud) before relying on it for a move.- See [Privacy](PRIVACY.md) for full details.## Billing@@ -88,21 +90,89 @@ Pulse Cloud billing is handled by Stripe. You can manage your subscription from## Migrating To/From Cloud+**Create Backup transfers only the included configuration, not the full+installation.** Metrics and audit history, incidents and queued notifications,+server-side agent inventory and enrolment state, profiles and assignments are+not included. Neither are TrueNAS, vSphere and Machine Availability connections,+local login credentials or deployment overrides. Contents depend on the+exporting version; see the [configuration-transfer scope](MIGRATION.md#configuration-transfer)+for the complete account. Imported API-token records do not reveal the original+tokens or establish that every agent is admitted.++Hosted automatic backups and this downloaded export are different things. If+you need excluded state, retain the source and establish a recoverable,+[consistent full-state backup](MIGRATION.md#full-state-recovery) before moving.+Do not assume access to the hosted filesystem or that a hosted backup can be+restored into your self-hosted installation. Do not mix encrypted files and keys+from different installations. Keep exports, passphrases and credentials private.++Import can activate monitoring and notification settings. Use an isolated trial+where available; if the hosted destination cannot be isolated, arrange a+single-active cutover before importing and retain independent monitoring during+the pause. Browser administrator access does not grant hosted filesystem or+service-control access. If a necessary hosting-side operation is unavailable,+stop before importing rather than cancel the source or run two connected copies.+### Self-Hosted → Cloud-1. **Export** from your self-hosted instance: **Settings → System → Recovery → Create Backup**.-2. **Import** into your Cloud instance: **Settings → System → Recovery → Restore Configuration**.-3. Update agent `--url` flags to point to your cloud URL.+1. Keep the self-hosted source intact and preserve the separate full-state+ backup if you need its history or excluded state.+2. Set up destination-local administrator access on Cloud. Keep the trial+ destination isolated from monitored systems, agents and notification+ destinations so two instances do not send duplicate alerts or remote actions.+3. **Export** from the source through **Settings → System → Recovery → Create+ Backup**, using a strong, unique passphrase stored separately. If Cloud+ already has useful configuration, export it first. **Restore Configuration**+ replaces the included settings and API-token records; it does not merge them.+4. Re-create the excluded connections and settings you need. Retarget existing+ agents using the [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),+ not by uninstalling or re-enrolling them. It preserves the saved identity and+ credential; use the procedure supported by that host's platform.+5. Complete the [cutover checks](#verify-the-move-before-retiring-the-source)+ before retiring the self-hosted source.### Cloud → Self-Hosted-1. **Export** from Cloud: **Settings → System → Recovery → Create Backup**.-2. Install Pulse on your own server (see [Install Guide](INSTALL.md)).-3. **Import** the backup.-4. Re-activate your license key (if switching to Pro self-hosted).-5. Update agent `--url` flags.--See [Migration Guide](MIGRATION.md) for detailed steps.+1. Keep the Cloud instance available until validation is complete; do not+ cancel it or discard the source merely because an export succeeded. Establish+ recovery for any excluded state you need before proceeding.+2. Install Pulse on your own server using the [Install Guide](INSTALL.md).+ Set up destination-local administrator access and keep the trial isolated+ from monitored systems, agents and notification destinations.+3. **Export** from Cloud through **Settings → System → Recovery → Create+ Backup**. Keep its passphrase separately and privately. Export any existing+ destination configuration first, then use **Restore Configuration** there;+ import replaces the included settings and API-token records, not a merge.+4. Re-create excluded connections and settings, and verify your Pro licence+ separately if using Pro self-hosted. Retarget existing agents with the+ [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),+ preserving their identity and private credential rather than creating a+ replacement token just for the move.+5. Complete the checks below before retiring the Cloud source.++### Verify the move before retiring the source++- Verify destination-local login, imported SSO mappings and the new callback+ address. Imported settings do not override every deployment-managed value.+- Keep HTTPS verification enabled for both the new installer download and the+ agent connection. An old endpoint's custom CA or certificate pin is not+ automatically trust for the new endpoint; follow the retargeting guide.+- Check fresh ordinary reports and agent admission at the destination, not+ just cached rows or a successful import. Re-create profiles and assignments+ before enabling remote actions. Missing history after configuration-only+ transfer does not prove collection failed.+- Check every expected platform and your existing notification delivery+ evidence without running two instances against the same destinations. Do+ not induce alerts, replay a queue or run a workload action merely to test the+ move; importing settings does not transfer queued notifications.+- If an import reports a reload/apply failure, settings may already have been+ written. Preserve both instances and inspect the error before repeating it.+ If validation fails, stop the trial destination before returning traffic to+ the intact source, check agent URLs and avoid two active writers.++See the [Migration Guide](MIGRATION.md#cut-over-and-verify) for the complete+cutover and recovery procedure. A successful configuration import is not proof+of full recovery.## FAQ@@ -120,7 +190,9 @@ Your data is retained for 30 days after cancellation. You can export your config### Can I switch between Cloud and self-hosted?-Yes. Use the export/import workflow described above. Your monitoring configuration is fully portable.+You can transfer the included configuration using the workflow above. It is+not a full installation copy: history, some connections and agent enrolment+state need separate handling. Verify the destination before retiring the source.## See Alsodiff --git a/frontend-modern/public/docs/CLOUD.md b/frontend-modern/public/docs/CLOUD.mdindex 74b0cacbc5..613e3734b1 100644--- a/frontend-modern/public/docs/CLOUD.md+++ b/frontend-modern/public/docs/CLOUD.md@@ -75,7 +75,9 @@ Relay is enabled by default on Cloud instances. Open **Settings → Pulse Mobile- Your monitoring data runs in an **isolated container** — no shared databases.- Data is stored encrypted at rest.- Backups are automated and encrypted.-- You can **export** your configuration at any time via **Settings → System → Recovery** and migrate to self-hosted if needed.+- **Create Backup** in **Settings → System → Recovery** downloads an encrypted+ configuration export, not a complete copy of the hosted installation. Check+ the [migration scope](#migrating-tofrom-cloud) before relying on it for a move.- See [Privacy](PRIVACY.md) for full details.## Billing@@ -88,21 +90,89 @@ Pulse Cloud billing is handled by Stripe. You can manage your subscription from## Migrating To/From Cloud+**Create Backup transfers only the included configuration, not the full+installation.** Metrics and audit history, incidents and queued notifications,+server-side agent inventory and enrolment state, profiles and assignments are+not included. Neither are TrueNAS, vSphere and Machine Availability connections,+local login credentials or deployment overrides. Contents depend on the+exporting version; see the [configuration-transfer scope](MIGRATION.md#configuration-transfer)+for the complete account. Imported API-token records do not reveal the original+tokens or establish that every agent is admitted.++Hosted automatic backups and this downloaded export are different things. If+you need excluded state, retain the source and establish a recoverable,+[consistent full-state backup](MIGRATION.md#full-state-recovery) before moving.+Do not assume access to the hosted filesystem or that a hosted backup can be+restored into your self-hosted installation. Do not mix encrypted files and keys+from different installations. Keep exports, passphrases and credentials private.++Import can activate monitoring and notification settings. Use an isolated trial+where available; if the hosted destination cannot be isolated, arrange a+single-active cutover before importing and retain independent monitoring during+the pause. Browser administrator access does not grant hosted filesystem or+service-control access. If a necessary hosting-side operation is unavailable,+stop before importing rather than cancel the source or run two connected copies.+### Self-Hosted → Cloud-1. **Export** from your self-hosted instance: **Settings → System → Recovery → Create Backup**.-2. **Import** into your Cloud instance: **Settings → System → Recovery → Restore Configuration**.-3. Update agent `--url` flags to point to your cloud URL.+1. Keep the self-hosted source intact and preserve the separate full-state+ backup if you need its history or excluded state.+2. Set up destination-local administrator access on Cloud. Keep the trial+ destination isolated from monitored systems, agents and notification+ destinations so two instances do not send duplicate alerts or remote actions.+3. **Export** from the source through **Settings → System → Recovery → Create+ Backup**, using a strong, unique passphrase stored separately. If Cloud+ already has useful configuration, export it first. **Restore Configuration**+ replaces the included settings and API-token records; it does not merge them.+4. Re-create the excluded connections and settings you need. Retarget existing+ agents using the [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),+ not by uninstalling or re-enrolling them. It preserves the saved identity and+ credential; use the procedure supported by that host's platform.+5. Complete the [cutover checks](#verify-the-move-before-retiring-the-source)+ before retiring the self-hosted source.### Cloud → Self-Hosted-1. **Export** from Cloud: **Settings → System → Recovery → Create Backup**.-2. Install Pulse on your own server (see [Install Guide](INSTALL.md)).-3. **Import** the backup.-4. Re-activate your license key (if switching to Pro self-hosted).-5. Update agent `--url` flags.--See [Migration Guide](MIGRATION.md) for detailed steps.+1. Keep the Cloud instance available until validation is complete; do not+ cancel it or discard the source merely because an export succeeded. Establish+ recovery for any excluded state you need before proceeding.+2. Install Pulse on your own server using the [Install Guide](INSTALL.md).+ Set up destination-local administrator access and keep the trial isolated+ from monitored systems, agents and notification destinations.+3. **Export** from Cloud through **Settings → System → Recovery → Create+ Backup**. Keep its passphrase separately and privately. Export any existing+ destination configuration first, then use **Restore Configuration** there;+ import replaces the included settings and API-token records, not a merge.+4. Re-create excluded connections and settings, and verify your Pro licence+ separately if using Pro self-hosted. Retarget existing agents with the+ [address-change procedure](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),+ preserving their identity and private credential rather than creating a+ replacement token just for the move.+5. Complete the checks below before retiring the Cloud source.++### Verify the move before retiring the source++- Verify destination-local login, imported SSO mappings and the new callback+ address. Imported settings do not override every deployment-managed value.+- Keep HTTPS verification enabled for both the new installer download and the+ agent connection. An old endpoint's custom CA or certificate pin is not+ automatically trust for the new endpoint; follow the retargeting guide.+- Check fresh ordinary reports and agent admission at the destination, not+ just cached rows or a successful import. Re-create profiles and assignments+ before enabling remote actions. Missing history after configuration-only+ transfer does not prove collection failed.+- Check every expected platform and your existing notification delivery+ evidence without running two instances against the same destinations. Do+ not induce alerts, replay a queue or run a workload action merely to test the+ move; importing settings does not transfer queued notifications.+- If an import reports a reload/apply failure, settings may already have been+ written. Preserve both instances and inspect the error before repeating it.+ If validation fails, stop the trial destination before returning traffic to+ the intact source, check agent URLs and avoid two active writers.++See the [Migration Guide](MIGRATION.md#cut-over-and-verify) for the complete+cutover and recovery procedure. A successful configuration import is not proof+of full recovery.## FAQ@@ -120,7 +190,9 @@ Your data is retained for 30 days after cancellation. You can export your config### Can I switch between Cloud and self-hosted?-Yes. Use the export/import workflow described above. Your monitoring configuration is fully portable.+You can transfer the included configuration using the workflow above. It is+not a full installation copy: history, some connections and agent enrolment+state need separate handling. Verify the destination before retiring the source.## See Alsodiff --git a/frontend-modern/src/features/docs/__tests__/cloudMigrationGuide.test.ts b/frontend-modern/src/features/docs/__tests__/cloudMigrationGuide.test.tsnew file mode 100644index 0000000000..713b29edbb--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/cloudMigrationGuide.test.ts@@ -0,0 +1,61 @@+import { readFileSync } from 'node:fs';+import { resolve } from 'node:path';+import { describe, expect, it } from 'vitest';+import { renderDocMarkdown } from '../docMarkdown';++const read = (file: string) => readFileSync(resolve(process.cwd(), '..', file), 'utf8');+const article = (name: string) => {+ const element = document.createElement('article');+ element.innerHTML = renderDocMarkdown(read(`docs/${name}.md`), name);+ return element;+};+const text = (element: Element) => element.textContent?.replace(/\s+/g, ' ') ?? '';++describe('Cloud configuration-transfer help', () => {+ it('ships the same scope warning before either migration direction', () => {+ expect(read('frontend-modern/public/docs/CLOUD.md')).toBe(read('docs/CLOUD.md'));+ const guide = article('CLOUD');+ const migration = guide.querySelector('#migrating-tofrom-cloud');+ const warning = migration?.nextElementSibling;+ expect(warning?.querySelector('strong')).not.toBeNull();+ expect(text(warning!)).toContain('not the full installation');+ expect(text(warning!)).toContain('agent inventory and enrolment state');+ expect(text(warning!)).toContain('TrueNAS, vSphere and Machine Availability');+ expect(text(guide)).not.toContain('fully portable');+ });++ it('keeps both ordered moves and their single-active, identity and recovery checks readable', () => {+ const guide = article('CLOUD');+ for (const name of ['Self-Hosted → Cloud', 'Cloud → Self-Hosted']) {+ const heading = [...guide.querySelectorAll('h3')].find((node) => text(node) === name);+ expect(heading?.nextElementSibling?.tagName).toBe('OL');+ expect(heading?.nextElementSibling?.querySelectorAll('li')).toHaveLength(5);+ expect(text(heading!.nextElementSibling!)).toContain('destination-local administrator access');+ expect(text(heading!.nextElementSibling!)).toContain('API-token records');+ }+ expect(text(guide)).toContain('single-active cutover before importing');+ expect(text(guide)).toContain('stop before importing');+ expect(text(guide)).toContain('rather than creating a replacement token');+ expect(text(guide)).toContain('settings may already have been written');+ expect(text(guide)).toContain('Do not induce alerts, replay a queue or run a workload action');+ expect(text(guide)).toContain('not proof of full recovery');+ expect(guide.querySelector('pre')).toBeNull();+ });++ it('routes every migration/retarget link to an existing guide and fragment', () => {+ const guide = article('CLOUD');+ for (const [name, fragment] of [+ ['MIGRATION', 'configuration-transfer'],+ ['MIGRATION', 'full-state-recovery'],+ ['MIGRATION', 'cut-over-and-verify'],+ ['UNIFIED_AGENT', 'moving-pulse-to-a-new-address'],+ ]) {+ const link = guide.querySelector(`a[href="/docs/${name}#${fragment}"]`);+ expect(link).not.toBeNull();+ expect(link?.hasAttribute('data-doc-link')).toBe(true);+ expect(article(name).querySelector(`[id="${fragment}"]`)).not.toBeNull();+ }+ expect(guide.querySelector('a[href="#verify-the-move-before-retiring-the-source"]')).not.toBeNull();+ expect(guide.querySelector('#verify-the-move-before-retiring-the-source')).not.toBeNull();+ });+});diff --git a/scripts/tests/test_cloud_migration_docs.py b/scripts/tests/test_cloud_migration_docs.pynew file mode 100644index 0000000000..6c54719541--- /dev/null+++ b/scripts/tests/test_cloud_migration_docs.py@@ -0,0 +1,84 @@+#!/usr/bin/env python3+"""Keep the hosted migration entry point within the actual export/agent scope.++These check instructions, not installed Cloud recovery or provider access.+The real encrypted-archive control is TestConfigurationMigrationArchiveScope.+"""++from pathlib import Path+import unittest+++ROOT = Path(__file__).resolve().parents[2]+++def guide():+ return (ROOT / "docs/CLOUD.md").read_text(encoding="utf-8")+++def section(text, heading, level):+ return " ".join(text.split(f"{level} {heading}\n", 1)[1].split(f"\n{level} ", 1)[0].split())+++class CloudMigrationDocsTest(unittest.TestCase):+ def test_in_app_guide_matches_canonical(self):+ self.assertEqual(guide(), (ROOT / "frontend-modern/public/docs/CLOUD.md").read_text())++ def test_export_scope_is_not_a_portable_installation_promise(self):+ text = section(guide(), "Migrating To/From Cloud", "##")+ for boundary in (+ "not the full installation", "Metrics and audit history",+ "incidents and queued notifications", "agent inventory and enrolment state",+ "profiles and assignments", "TrueNAS, vSphere and Machine Availability",+ "local login credentials or deployment overrides", "exporting version",+ "MIGRATION.md#configuration-transfer", "do not reveal the original tokens",+ "Hosted automatic backups and this downloaded export are different things",+ "Do not assume access to the hosted filesystem", "MIGRATION.md#full-state-recovery",+ "Do not mix encrypted files and keys", "Keep exports, passphrases and credentials private",+ ):+ with self.subTest(boundary=boundary):+ self.assertIn(boundary, text)+ self.assertNotIn("fully portable", guide())+ self.assertIn("not a complete copy of the hosted installation",+ section(guide(), "Data & Privacy", "##"))++ def test_both_directions_preserve_access_source_and_destination(self):+ for heading in ("Self-Hosted → Cloud", "Cloud → Self-Hosted"):+ text = section(guide(), heading, "###")+ with self.subTest(direction=heading):+ for boundary in ("destination-local administrator access", "notification destinations",+ "API-token records", "not", "merge", "passphrase", "export",+ "excluded connections and settings", "before retiring"):+ self.assertIn(boundary, text)+ hosted_exit = section(guide(), "Cloud → Self-Hosted", "###")+ self.assertIn("do not cancel it or discard the source", hosted_exit)+ self.assertIn("verify your Pro licence separately", hosted_exit)++ def test_retargeting_preserves_identity_and_does_not_inherit_endpoint_trust(self):+ text = section(guide(), "Migrating To/From Cloud", "##")+ self.assertEqual(text.count("UNIFIED_AGENT.md#moving-pulse-to-a-new-address"), 2)+ for boundary in ("saved identity and credential", "host's platform",+ "rather than creating a replacement token", "HTTPS verification enabled",+ "installer download", "agent connection", "certificate pin",+ "not automatically trust for the new endpoint", "fresh ordinary reports",+ "agent admission", "before enabling remote actions"):+ with self.subTest(boundary=boundary):+ self.assertIn(boundary, text)+ self.assertNotIn("Update agent `--url` flags", text)+ self.assertNotIn("```", text, "No generic credential, reinstall or hosted-filesystem recipe")++ def test_import_errors_and_cutover_do_not_trigger_destructive_diagnostics(self):+ text = section(guide(), "Migrating To/From Cloud", "##")+ for boundary in ("Import can activate monitoring", "single-active cutover before importing",+ "retain independent monitoring", "does not grant hosted filesystem",+ "stop before importing", "reload/apply failure",+ "settings may already have been written", "before repeating it",+ "stop the trial destination", "intact source", "avoid two active writers",+ "Do not induce alerts, replay a queue or run a workload action",+ "not proof of full recovery", "Missing history", "does not prove collection failed"):+ with self.subTest(boundary=boundary):+ self.assertIn(boundary, text)+++if __name__ == "__main__":+ unittest.main()