Pulse/docs/MIGRATION.md

# 🚚 Migrating Pulse

**Updated for Pulse v4.24.0+**

## 🚀 Quick Migration Guide

### ❌ DON'T: Copy Files
Never copy `/etc/pulse` or `/var/lib/pulse` manually. Encryption keys and credentials will break.

### ✅ DO: Use Export/Import

#### 1. Export (Old Server)
1.  Go to **Settings → Configuration Management**.
2.  Click **Export Configuration**.
3.  Enter a strong passphrase and save the `.enc` file.

#### 2. Import (New Server)
1.  Install a fresh Pulse instance.
2.  Go to **Settings → Configuration Management**.
3.  Click **Import Configuration** and upload your file.
4.  Enter the passphrase.

## 📦 What Gets Migrated

| Included ✅ | Not Included ❌ |
| :--- | :--- |
| Nodes & Credentials | Historical Metrics |
| Alert Settings | Alert History |
| Email & Webhooks | Auth Settings (Passwords/Tokens) |
| System Settings | Update Rollback History |
| Guest Metadata | |

## 🔄 Common Scenarios

### Moving to New Hardware
Export from old → Install new → Import.

### Docker ↔ Systemd ↔ LXC
The export file works across all installation methods. You can migrate from Docker to LXC or vice versa seamlessly.

### Disaster Recovery
1.  Install Pulse: `curl -sL https://github.com/rcourtman/Pulse/releases/latest/download/install.sh | bash`
2.  Import your latest backup.
3.  Restored in < 5 minutes.

## 🔒 Security

*   **Encryption**: Exports are encrypted with PBKDF2 (100k iterations).
*   **Storage**: Safe to store in cloud backups or password managers.
*   **Passphrase**: Use a strong, unique passphrase (min 12 chars).

## 🔧 Troubleshooting

*   **"Invalid passphrase"**: Ensure exact match (case-sensitive).
*   **Missing Nodes**: Verify export date.
*   **Connection Errors**: Update node IPs in Settings if they changed.
*   **Logging**: Re-configure log levels in **Settings → System → Logging** if needed.