Back up, restore, and upgrade self-hosted Plane with Prime CLI

Prime CLI after the install

0:02Prime CLI is the command-line tool that installs self-hosted Plane on Docker.

0:09After the install, it backs the instance up, restores it, upgrades it, and checks its health.

0:16You'll see each one, and how a single backup moves Plane to a new server. Let's take a closer look.

Back up and restore

0:27To take a backup, run prime-cli backup. It packs /opt/plane into one compressed file while Plane keeps running.

0:38That's plane.env, the compose file, and the data folder, which holds the database and uploads. The proxy's certificates and the logs go in too.

0:50An external database or S3 bucket isn't in the file, so back those up with their own tools.

0:57The file goes to /opt/plane/backups, named with the Plane version and the time you took it.

1:05Plane keeps writing while a backup runs. For a consistent copy of the database, run prime-cli stop first, then start Plane again.

1:16prime-cli restore needs the file's name. Leave it out, and it only lists the backups you can choose.

1:24It says what it will do and asks you to confirm. Then it stops Plane and takes a safety backup of the instance as it is.

1:33Next, it puts the backup's files in place and starts Plane. Work items and files added after that backup are no longer there.

1:43If a later step fails, Prime CLI restores the safety backup. That file stays in the folder, so you can undo a restore the same way.

1:57To check for a new release, run prime-cli status.

Check status and upgrade

2:01It shows your version, the latest one, and how many releases you're behind.

2:07Before you upgrade, run prime-cli update-cli. Prime CLI won't upgrade Plane until it's up to date itself.

2:17Then run prime-cli upgrade. It names both versions and waits for a yes.

2:24Once you confirm, it backs up the instance and downloads the new release, then checks the settings and free disk space. Plane keeps running through all of it.

2:35Downtime starts when it stops the services. It removes the old images, saves a copy of the database, and creates fresh containers.

2:45Next, the migrator updates the database, and the last five lines of its log scroll by. Then Prime CLI waits for the API to start.

2:55It ends by printing the new version and your address. Plane is back, and the downtime is over.

3:02If a step after the stop fails, it restores the backup it took first. Then, if Plane isn't running, run prime-cli start.

3:13After a successful upgrade, it deletes that backup. Take your own first, so you still have one to restore.

3:21To choose a release other than the latest, add --version. There's no downgrade. To go back, restore a backup from the older version.

3:35To check every service, run prime-cli healthcheck. Running services read healthy,

Keep it healthy, and move it

3:42finished jobs read gracefully stopped, and switched-off ones read disabled.

3:48Anything else makes the command fail, so scripts can catch it. --watch refreshes the table until you press Ctrl+C.

3:58From any machine, call /api/ready/ on your domain, with the slash at the end.

4:05It returns 200 when the API can reach the database and cache, and 503 when it can't.

4:13For a service's logs, run prime-cli logs with its name. --tail 50 starts at the last fifty lines.

4:23--follow keeps reading until you press Ctrl+C. Without a name, you get every service, each line tagged with its service.

4:33When you need support, run prime-cli bundle. It writes one file with recent logs, container details, and a summary page.

4:43--since 1h keeps the last hour, and --with-config adds your settings. The bundle masks passwords, keys, and tokens.

4:55To run more background jobs at once, add workers. prime-cli scale view lists every service you can scale.

5:03prime-cli scale worker 3 writes the new count to plane.env and starts the extra workers, without stopping Plane.

5:13Keep the beat worker at one replica, or scheduled jobs run more than once. Never take Argus or a migrator above one either.

5:22To move to a new server on the same domain, unlink your license keys first.

5:29Then stop Plane and take a backup.

5:33Install Plane on the new server, copy the backups folder into /opt/plane, and restore your backup.

5:42Then point the domain at the new server, and activate your license keys there.

5:48Take your own backup before every upgrade, and check health when it's done. To change servers, restore a backup on the new one.