Moving a self-hosted OpenBoxes to Lift: what comes across

If you already run OpenBoxes on your own server, moving to OpenBoxes Lift is a migration of your existing database, not a re-keying exercise. This article is about what to expect before you start: what you hand over, what comes across and what does not, what happens to your users' passwords, and how to plan the switch so nothing entered on the day is lost. The step-by-step instructions are in Migrating data.

What you hand over#

You give Lift a copy of your OpenBoxes database, in one of two forms. In the portal, go to Import Data and choose Self-hosted OpenBoxes; the export guide there starts with one question, whether you can run a database export command, and shows the matching instructions.

A database export (recommended). One command on your server produces a compressed .sql.gz file. The guide shows it for MySQL (mysqldump) and MariaDB (mariadb-dump), with the options it needs, and how to wrap it in docker exec if your database runs in a Docker container. If your database is a managed service, such as a DigitalOcean Managed Database or AWS RDS, the guide shows the same export against that host instead. A "download backup" or export file from your provider works too.

The export tool (advanced). If running an export command is not possible but the database can be reached, a standalone export tool reads the database directly and produces an openboxes-export.zip. It needs Java 17 or newer on the machine that runs it, and it only reads: it never changes your database.

If neither fits, the guide's Not sure option suggests asking whoever runs your server for a database export, or emailing our support team to work it out with you.

Either way, your live OpenBoxes keeps running while you take the copy.

What happens to the file#

You upload the file on the same page. A database export is restored in an isolated sandbox so it can be read; nothing touches your Lift instance until you confirm.

Before anything is written, you see a preview:

• The table counts it found, table by table.
• Warnings, for example when your OpenBoxes version could not be determined, or when it is old enough that its transaction history needs a closer look (see below).

If the file cannot be used, the preview says Your export failed validation and lists why, and you can try another file. If it looks right, Migrate now loads it.

There is also an optional Describe your data box: tell us roughly how many warehouses, products, inventory items and users you have, and the preview (what was found) and the final report (what was imported) are compared against your estimate, line by line, with any amounts that differ pointed out. It is a cheap check worth the minute it takes.

When the load finishes, the report shows how many records were loaded, how many reference rows were reused, and how many users were invited, with any warnings.

What comes across#

The migration carries your master data and your history:

• Products, categories and units of measure
• Locations and warehouses
• Inventory: stock on hand with lot numbers and expiry dates
• Suppliers and organizations
• Transaction history: shipments, orders, requisitions and receipts
• Your users' names and email addresses

What does not come across#

• Passwords. Passwords never reach your Lift instance: the migration leaves them out, and each user sets a new one from a "set your password" invitation email. Someone who already has a Lift account, such as the account owner who signed up, is not invited again.
• User photos and personal dashboard layouts. These are left out of the copy.
• Login sessions and API keys. Nothing that would let an old session or credential carry over.
• OpenBoxes' reporting warehouse tables (the fact and dimension tables) are left out of the copy.
• Everything outside the database: your server configuration file, custom code, and anything else on the server's disk.

If you rely on something that is not in the "comes across" list, ask us before you start rather than after.

If your OpenBoxes version is older or newer#

Lift runs OpenBoxes 0.9.9 on the Shared plan, and your server may be on a different release. Two things help here:

• Small schema differences do not stop the load. Where a table in your data has a column that the Lift version does not, that column is left out with a warning rather than failing the whole load.
• Older releases get a specific warning. OpenBoxes 0.9.5 changed how inventory transactions are stored. If your server runs 0.9.4, the preview warns that its transaction history predates that change and may need review after the import. On releases before 0.9.4, it warns that the transaction history may not migrate cleanly. Master data (products, locations and the rest) is still imported, on a best-effort basis for the oldest releases.

If the preview reports something you do not understand, talk to us before you click Migrate now.

Your users on day one#

Plan for the invitations. Nobody can sign in with their old password, so every migrated user needs to open their invitation email and set a password. Three things to know:

• Everyone with an email address in your old user list is invited, including users you had deactivated, so tidy the list before you export.
• The link in the email works for 12 hours. After that, use Forgot password on the sign-in page. Migrating on the morning of the switch means most people open their email while the link still works.
• Tell your team before the switch that the email is coming, from whom, and that it is expected. It saves a morning of "I can't log in" messages.

Planning the switch#

A migration copies your database as it was at the moment of the export. Anything entered on the old server afterwards stays there.

The migration is meant to run once per instance. Running it a second time into the same instance does not replace the first load; it adds a second copy of your records. If you think you need to re-run it, ask support first.

So plan it like this:

• Check early, migrate once. Upload a recent export and read the preview; do not click Migrate now until the cutover.
• A quiet cutover. Pick a time with little activity, ideally a morning, ask people to stop entering data, take the export, migrate, check the result, then switch everyone to Lift.

Then check the result before you switch: compare the product count, the stock on hand of a few products you know, and the most recent receipt against the old server. Keep the old server, or at least a backup of its database, until you are confident.

Once your data is on Lift, take an on-demand backup (Backups, then Run backup now) before you start changing things, so you have a clean starting point to return to.

Summary#

• Hand over a database export (.sql.gz) or the export tool's .zip; your live server keeps running.
• You see table counts, warnings and a reconciliation before anything is written, and confirm with Migrate now.
• Products, locations, inventory with lots and expiry, suppliers, transaction history and users come across.
• Passwords never reach your Lift instance: every user sets a new one from an invitation email, whose link works for 12 hours.
• Read the preview early, but click Migrate now once, at the cutover, and check the result before switching.

Get started compares the plans.