Upgrade Helpin

helpin upgrade moves an installation to a newer release safely. It checks that the path is supported, takes a recovery backup, applies migrations, and verifies the result. If anything fails, it stops and tells you how to recover.

Before you upgrade

Read the release notes for the target version.
Make sure the current installation is healthy: helpin doctor --dir /srv/helpin.
Plan a short maintenance window. Services stop while the backup and migration run.
Check you have free disk space for a full backup.

Upgrade

helpin upgrade --dir /srv/helpin --backup /srv/backups/pre-upgrade

Without --version, the CLI finds the newest published Community release. To pin a specific one:

helpin upgrade --dir /srv/helpin --version <release-tag> --backup /srv/backups/pre-upgrade

The CLI asks before any downtime. Add --yes for automation.

What happens

Compatibility check. The target release must explicitly list your installed version as a tested upgrade source. Helpin never jumps to an untested path silently. If the newest release isn't compatible, choose a compatible --version.
Pre-flight. The current stack must be healthy, with a clean migration ledger and unmodified bundle files. Target images are pulled before downtime starts.
Recovery backup. A complete, consistent backup is taken.
Replace and migrate. The new bundle is installed and database migrations run.
Verify. Migrations, service health, and API readiness are checked.

Your .env, apps.json, and Caddyfile are preserved. New settings introduced by the release are merged in with defaults. Existing keys are never rotated.

If an upgrade fails

A failed migration or readiness check stops the new services and prints the backup path and a ready-to-run restore command. Recover into a new directory:

helpin restore --backup /srv/backups/pre-upgrade --dir /srv/helpin-recovered --yes --no-start
helpin start --dir /srv/helpin-recovered
helpin doctor --dir /srv/helpin-recovered

Make sure the failed installation is stopped before you start the recovered one on the same ports. The failed installation is kept untouched so you can inspect it or share redacted logs.

Note: Schema migrations can't be undone by changing an image tag. Recovery always means restoring the matching pre-upgrade data and keys. Changes made after the backup was taken aren't included.

Things to avoid

Don't edit HELPIN_VERSION in .env to upgrade. Version variables are pins, not upgrade instructions.
Don't modify managed bundle files. Keep your settings in .env, apps.json, and Caddyfile, which upgrades preserve.
Don't delete the pre-upgrade backup until you've verified the upgraded installation.

Upgrading changes to PostgreSQL, Redis, NATS, Garage, or Temporal images needs a separate, documented procedure. Release notes call these out.

Was this article helpful?