Moving an installation to another host

Migrating PEART is copying three things, in one specific order. Get the order wrong and the new host generates a master key of its own, at which point the backup you are about to restore cannot be read by the installation you just built.

What has to travel

What	Where it lives	Why it cannot be skipped
The master key	master_key_path, outside the data directory	The backup artifact never contains it, by design. Without the original key, the evidence and the backups are unreadable, with no recovery.
The backup artifact	wherever peart backup -out wrote it	Database, evidence and renditions, encrypted to that master identity.
The configuration	/etc/peart/config.yaml and the environment files	Paths, surfaces, the render token. Review it on the new host rather than copying it blindly.

The order that matters

1. Install on the new host, and do not start the services. Binaries, the render sidecar, the units, the directories. Nothing that opens the database yet.
2. Put the original master key in place, at the path master_key_path names, owned by the service user, mode 0600. Do this before the first boot. If the data volume is encrypted, do it after the volume is open and mounted: a key written while the mount point is still an empty directory on the root filesystem disappears under the volume, and the first boot then generates a new identity.
3. Restore the backup into the new host's data directories, with that same master identity.
4. Run peart migrate, so a backup from an older version reaches the schema the new binaries expect.
5. Start the services, and verify: the login page answers, a published finding opens, and a report generates (the last one exercises the render sidecar, which is the part a fresh host most often lacks).

Why step 2 comes before the first boot

On first boot, a PEART that finds no key at master_key_path generates one and saves it. That is the right behaviour for a new installation and the wrong one for a migration: the host now holds a master identity that never encrypted anything you have. A restore with a different identity than the one the artifact was encrypted to is refused outright, which is the safe failure, and the confusing one if you did not expect it.

The fix for that state is to stop the services, put the original key in place, and restore again. Nothing is lost as long as the original key still exists somewhere, which is exactly why it is exported and kept apart from the data backup.

Before you decommission the old host

Keep the old host, or at least its key and its last backup, until the new one has proven itself: a successful login, a finding read end to end, a report generated, and a peart fsck with nothing to say. Only then wipe the old disk.

If the old host is unreachable and the key is gone, no procedure recovers the evidence. That is the declared limit of the encryption model, not a gap in this page.