OpenBoxes backups: what to back up and how to test a restore

A backup you have never restored is a hope, not a plan. This article covers what to back up for an OpenBoxes installation, how often, how to prove a restore works, and what OpenBoxes Lift does for you on Shared and Dedicated. The first half applies to anyone running OpenBoxes on their own server; the second half describes Lift.

What to back up on a self-hosted OpenBoxes#

An OpenBoxes installation has three things worth protecting.

1. The database. OpenBoxes 0.9.x runs on MySQL 8 or MariaDB 10.x (older 0.8.x installs often run MySQL 5.7), and almost everything lives there: products, locations, every stock transaction, orders, shipments and users. Files uploaded through OpenBoxes' document upload are stored in the database too, so a full database backup carries them. This is the part you cannot rebuild.
2. The configuration file. OpenBoxes reads its settings (the database connection, the server URL, mail settings) from a file such as openboxes-config.properties, openboxes-config.groovy or openboxes.yml, usually under a .grails directory. Keep a copy, without the passwords in plain text if you can.
3. The version you run. Write down the exact OpenBoxes version. OpenBoxes applies its database changes automatically when it starts, so a backup restored into a different version can be changed on first start. To restore cleanly, restore into the same version first.

The application itself (the WAR file and Tomcat) can be reinstalled from a download. The data cannot.

Taking a consistent database backup#

The standard tool is mariadb-dump (called mysqldump on MySQL and on older MariaDB). Use --single-transaction, which takes a consistent snapshot of InnoDB tables without locking them, so OpenBoxes can keep running while the dump is taken. InnoDB is the default storage engine on MySQL 8 and MariaDB 10; it is worth checking that your tables use it.

An example, which assumes the database is called openboxes and the credentials are in an option file rather than on the command line:

set -o pipefail
mariadb-dump --single-transaction --routines --triggers openboxes \
  | gzip > /backups/openboxes-$(date +%F).sql.gz

On MySQL or an older MariaDB, replace mariadb-dump with mysqldump. Three details that catch people out:

• set -o pipefail, in a bash script, makes the script fail when the dump fails. Without it, a failed dump still produces a small, valid gzip file and the script reports success.
• Keep passwords out of the command line. Put them in a client option file readable only by the backup user, so they do not appear in the process list or shell history.
• Check the size and the ending. A dump that finished cleanly ends with a -- Dump completed line. A file much smaller than yesterday's deserves a look.

How often, and for how long#

Two questions set the schedule.

• How much work can you afford to re-enter? If the answer is one day of receipts and issues, back up at least nightly. If it is an hour, you need something more frequent than a nightly dump.
• How far back might you need to go? A mistake is not always noticed the same day. Keeping only last night's backup protects you from a failed disk, not from a bad import discovered a week later.

A common pattern is to keep several generations: for example, the last 7 daily backups, 4 weekly ones and 12 monthly ones. Adjust it to your own risk and storage.

Also take a backup immediately before anything risky: an upgrade, a large import, or a bulk change.

Keep a copy somewhere else#

A backup on the same server as the database shares its fate. Keep at least one copy off the server, and ideally one in a different location or with a different provider, so that losing the server, the building or the account does not also lose the backups. Encrypt copies that leave the server: a dump contains your stock data, the people in your system and their login credentials.

Prove the restore works#

On a schedule (quarterly is a reasonable start), restore a recent backup somewhere that is not production and check it:

One trap first. OpenBoxes creates more than 50 database views, and a dump records each view with a DEFINER clause naming the database user that created it, typically `openboxes`@`localhost`. Restoring on another server, or as a different user, then either fails or leaves views that error when OpenBoxes uses them. Do one of these:

• Create the same user on the test server (same name and host) before loading the dump, or

• strip the DEFINER clauses while loading, so each view is owned by the user doing the restore:

  gunzip < /backups/openboxes-2026-09-27.sql.gz \
    | sed -E 's/DEFINER=`[^`]+`@`[^`]+`//g' \
    | mariadb openboxes_restore_test
  

Then:

1. Create a scratch database on a separate server, for example openboxes_restore_test, and load the dump into it. If you did not create the same user, use the sed command above instead of this one:

   gunzip < /backups/openboxes-2026-09-27.sql.gz | mariadb openboxes_restore_test
   

2. Start an OpenBoxes of the same version against it.

3. Sign in and check a few things you know: the number of products, the stock on hand of two or three items, the most recent receipt.

4. Time it. How long the restore took is how long you would be without your system in a real incident. Write it down.

If the restore fails or the numbers do not match, you have found out on a quiet day rather than during an incident.

What OpenBoxes Lift does on Shared and Dedicated#

On OpenBoxes Lift, backups are taken for you. What happens depends on your plan.

Shared#

• Nightly backups, taken by Lift at around 02:15 UTC.
• Each one appears on the Backups page in the portal sidebar, with when it was taken and whether it completed.
• Backups are kept for 30 days.
• To keep them longer, a retention add-on is available once your subscription is paid: 90 days for $15/month ($144/year) or 1 year for $30/month ($288/year). One retention length is active at a time. A longer retention changes how far back your backups go, not how recent the newest one is, and the longer history builds from the day you add it: backups already deleted do not come back.

Dedicated#

• Nightly backups at 04:00 UTC, taken by the platform's database operator, kept for 30 days.
• These scheduled backups are not listed on the portal's Backups page. If you need to restore from one, ask in the in-portal chat and our team will arrange it.
• The retention add-on is not sold on Dedicated.

On every plan: on-demand backups#

Before a large import or a stock count, go to Backups and click Run backup now. The button is disabled while a backup is already running, and the new backup appears as a row once it completes. The Backups page lists each backup with its status and size, and offers a download once it is ready.

Restoring#

The account owner can restore any backup listed on the Backups page without a support ticket:

1. Go to Backups in the portal sidebar.
2. Open the menu on the backup you want.
3. Choose Restore from this backup….
4. Type your subdomain to confirm, then start the restore.

A restore replaces your instance's current data with the backup, and anything entered since that backup was taken is lost. The instance is unavailable while the restore runs. If you might want the current state back, take an on-demand backup first.

The full details are in the Backups section of Instance management.

Summary#

• On a self-hosted OpenBoxes, back up the database with --single-transaction, keep the configuration file and note the version.
• Back up at least nightly and before every risky change, keep several generations, and keep a copy off the server.
• Test a restore on a schedule, into the same OpenBoxes version, and time it.
• On Lift, Shared backups run nightly and are listed on the Backups page for 30 days (longer with an add-on); Dedicated backups run nightly and are restored through our team; on-demand backups and owner restores work from the portal.

Plan prices, including the retention add-on, are on the pricing page.