OpenBoxes upgrade checklist: before, during and after

An OpenBoxes upgrade is mostly waiting: you deploy a new WAR file, start Tomcat, and OpenBoxes changes your database to match the new version before it serves a single page. The preparation decides whether that wait ends well. This checklist covers what to do before, during and after an upgrade of a self-hosted OpenBoxes, and what changes if OpenBoxes Lift hosts it for you.

It does not replace the release notes or OpenBoxes' own upgrade guide, which covers upgrade strategies and rollback planning. Read those too.

What actually happens when the new version starts#

Knowing the mechanism makes the rest of the checklist make sense.

When OpenBoxes starts, it runs its database migrations before anything else. It uses Liquibase, and the sequence is:

1. Every database view is dropped. OpenBoxes creates dozens of views, and they are rebuilt at the end.
2. The migrations run in order, from the release your database is on to the release you just deployed. If you skip several versions, the migrations of every version in between run in the same start.
3. The views are rebuilt.

Only then does the application finish starting. The log shows Running liquibase changelog(s) ... at the beginning and All migrations ran successfully! when it is done. OpenBoxes' own code warns that the migration log may stay quiet until the whole run completes, which makes a long migration look like a hung server. Background jobs wait until the migrations have finished.

Two consequences follow. A large database can take a long time to start after an upgrade. And there is no automatic way back: the migrations change your schema, so returning to the old version means restoring a backup taken before the upgrade.

Before the upgrade#

1. Know both version numbers#

Write down the exact version you run today and the one you are moving to. You need both to read the right release notes and to restore cleanly if you have to go back.

2. Read the release notes for every version in between#

Not only the target version: every release between yours and it. Release notes are where breaking changes live. Two examples from the 0.9.x line show why:

• The database. The 0.9.x line is supported on MySQL 8 or MariaDB 10, and 0.9.5 removed MySQL 5.7 support outright.
• OpenBoxes 0.9.5 introduced a new structure for inventory transactions. If you are crossing that release, read its notes on how existing transactions are handled before you start.

3. Check the database and Java versions#

If your database is older than the target release supports, upgrade the database first, as a separate change on a separate day, and let OpenBoxes run on it for a while before the application upgrade. Two changes at once make any problem twice as hard to diagnose.

The 0.9.x line is built for Java 8 and runs as a WAR in Tomcat. Check what the release you are moving to expects.

4. Take a backup and prove it restores#

Take a full database backup immediately before the upgrade, and keep the old WAR file and your configuration file (openboxes-config.properties, openboxes-config.groovy or openboxes.yml, usually under .grails). Those three things are your way back.

A backup you have never restored is not a way back yet. OpenBoxes backups: what to back up and how to test a restore covers taking a consistent dump and the view-ownership trap when restoring on another server.

5. Rehearse on a copy#

Restore last night's backup onto a test server, deploy the new version against it and start it. This is the single most useful step on the list:

• You find out whether the migrations succeed on your data, not on a clean database.
• You find out how long they take. Time the start from the first log line to the moment you can sign in. That is your downtime estimate for the real upgrade.
• You can check your own workflows on the new version before your team depends on it: receive a shipment, create a stock movement, run the reports you use every week.

6. Pick a window and tell people#

Choose a quiet time, long enough for your rehearsal time plus a margin, and ask everyone to stop entering data. Anything entered after your backup and before a restore would be lost if you have to go back.

During the upgrade#

1. Stop Tomcat cleanly, so nothing is writing to the database.
2. Take the final backup now, with the application stopped.
3. Deploy the new WAR and start Tomcat. Make sure only one OpenBoxes is running against this database, so only one process is migrating it.
4. Watch the log and do not interrupt it. Wait for All migrations ran successfully!. If the rehearsal took 40 minutes, a quiet log at minute 20 is expected.

If the start is interrupted#

Liquibase records a lock in a table called DATABASECHANGELOGLOCK while it migrates. If the process is killed mid-migration (a restart, a server reboot, a health check that gave up), the lock can stay behind. The next start waits for it for about five minutes, then fails with Could not acquire change log lock.

To check, look at the table:

SELECT * FROM DATABASECHANGELOGLOCK;

A row with LOCKED set to 1 and no OpenBoxes process running means a stale lock. The LOCKEDBY column names the host that took it, which tells you whether that process could still be alive. Only when you are sure nothing is migrating, release it and start again:

UPDATE DATABASECHANGELOGLOCK SET LOCKED=0, LOCKGRANTED=NULL, LOCKEDBY=NULL WHERE ID=1;

An interrupted migration is also a good reason to consider restoring the pre-upgrade backup and starting over, rather than continuing from a half-applied state.

After the upgrade#

The first start is not the end of the heavy work. By default, OpenBoxes also refreshes several of its reporting tables every time it starts (stock-out data, demand data, product availability and the order summary). On a large database that can keep the database busy for a while after the application is back, so a slow first hour is not necessarily a problem with the new version.

Then check it properly:

• Sign in as a few different users, including one with limited permissions.
• Compare numbers you know. Product count, stock on hand for two or three items, the most recent receipt.
• Run the workflows you tested in the rehearsal.
• Open the dashboard and your usual reports. They depend on the views and reporting tables that were rebuilt.

Keep the pre-upgrade backup for at least as long as it would take someone to notice a problem.

Going back#

If you have to roll back: stop Tomcat, restore the pre-upgrade backup, redeploy the old WAR with the old configuration file, and start it. Then work out what went wrong on the test server, not on production.

If OpenBoxes Lift hosts it for you#

On OpenBoxes Lift, none of this is your job. The Shared plan runs OpenBoxes 0.9.9, and on every plan upgrades and patching are handled by us: you never deploy a WAR, run a migration or clear a changelog lock. The Version line on your Instance page in the portal shows the OpenBoxes version your instance runs.

What stays yours is the same thing that matters on your own server: a backup before a big change. Before a large import or a bulk update, go to Backups in the portal and click Run backup now. The Instance management guide covers instance details and backups.

If you are weighing whether to keep upgrading your own server, Moving a self-hosted OpenBoxes to Lift explains what comes across when you move, and Get started compares the plans.

Summary#

• An upgrade runs the database migrations of every version between yours and the target on the first start, and there is no automatic downgrade.
• Read every release's notes in between; 0.9.5 alone removed MySQL 5.7 support and changed how inventory transactions are stored.
• Back up, prove the restore, and rehearse on a copy to learn how long the migrations take on your data.
• Never interrupt a migration; if one is interrupted, check DATABASECHANGELOGLOCK before starting again.
• On Lift, upgrades are handled for you; take an on-demand backup before large changes of your own.