Upgrade and Rollback

Upgrade

Goal: Move an existing deployment to a newer Hivel release without losing data, and revert cleanly if needed.

Pre-Upgrade Steps

Before starting any upgrade:

1. Take a manual RDS snapshot (see Backup and Restore). This provides a known-good restore point if the upgrade fails.

2. Learn what's changing: Contact your Hivel account contact or email [e-mail] to get:

   • Which service image tags are changing

   • Whether this release includes a new database migration

   • Any additional steps required for this specific release

3. Note the migration status: Record whether a new migration is included. This determines Step 3 of the upgrade

Upgrade Execution

Step 1: Stop Services

On the VM:

./deploy.sh --stop

Step 2: Update Images

On the VM:

./deploy.sh --update

Step 3: Run Database Migration (if included)

Only if Hivel confirmed a new migration is included.

a. Switch to Phase 1 (root/master) credentials in config/.env (Environment Configuration). Migrations require elevated privileges and will fail against the application-user credentials left from your last install.

b. Run the migration:

./deploy.sh --service flyway-migration

c. Once migration completes successfully, switch config/.env back to Phase 2 (application-user) credentials before continuing.

Skip this entire step if no new migration is included.

Step 4: Restart Services

On the VM:

./deploy.sh --start

Step 5: Validate the Upgrade

Run verification commands on the VM:

./deploy.sh --status
./deploy.sh --health

Both commands should show every service as Up/healthy. Re-run the full checklist from Verification and Access: endpoints, UI, and integrations should all pass.

Note: Additional Steps May Apply

Confirm with [e-mail] whether your specific release requires additional steps beyond the steps above.

Rollback (If Upgrade Fails)

Step 1: Assess the Situation

• Did this release include a database migration? (Check your pre-upgrade notes or contact Hivel.)

• Are services failing validation or health checks?

Step 2: Revert Application Code

1. Revert to the previous service image tags (undo the tags you updated in Step 2 of upgrade)

2. Redeploy:

   ./deploy.sh --update

Or for individual services:

   ./deploy.sh --service <service-name>

Step 3: Restore Database (if migration was included)

Skip this step if no migration was included in the release.

If the release included a database migration, reverting application code alone is insufficient. Flyway migrations cannot be easily reversed.

1. Contact Hivel support before proceeding: running older application code against an already-migrated schema can behave unpredictably

2. Restore the pre-upgrade RDS snapshot you took in Pre-Upgrade Steps (see Backup and Restore)

3. Re-run the Validation Checklist to confirm the rollback succeeded

Back to Backup and Restore

Uninstall and Cleanup