Live Box upgrades

Record the current state

Before changing the checkout, record the deployed commit, package lockfile, database backup, and service health. Commit or stash intentional local changes.

git status --short
git rev-parse HEAD
box --version
box status
box update --check

Take a database backup using the deployment provider’s normal backup process. Do not rely on an application rollback to reverse a database migration.

Upgrade the CLI

Use a current Box CLI before updating package state:

box upgrade --check
box upgrade
box --version

box upgrade changes the CLI binary only. It is safe to check or perform before touching the Box checkout.

Update the Box checkout

Run the package update from the Box root:

box update --check
box update
git diff -- package.json package-lock.json

box update resolves the entitled package graph as one compatible closure, refreshes stale lockfile entries, regenerates dashboard route stubs, detects logical App Router collisions, and runs a production build. It reports success only after that build passes.

Commit the package and lockfile changes so the deployment uses the exact graph you tested:

git add package.json package-lock.json console/scripts
git commit -m "chore: update Box packages"
git push

Rebuild and deploy

Use the Box’s normal deployment pipeline. For a Docker Compose deployment:

docker compose up -d --build

For Railway or another managed provider, deploy the commit produced in the previous step. Do not restart an old image and call it an upgrade; the image must be rebuilt from the updated lockfile.

Let the engine migrate

The engine applies pending package migrations during startup. Keep only one migration owner running while the new release starts, and inspect its startup logs before increasing traffic.

For bounded operator shifts, the additive migration:

• keeps existing operator PIN verifiers unchanged;
• assigns existing operators a default shift duration of 360 minutes;
• adds session expiry and closure metadata;
• reconciles historical duplicate open sessions; and
• enforces one open session per tenant and operator.

No plaintext PIN migration is required. Merchants do not need to reset existing PINs. They can change an operator’s limit later from POS Operations → Operators → Edit operator.

Verify the Box

At minimum, verify:

curl --fail https://api.your-box.example/health

Then sign in to the merchant dashboard and check:

• Products shows Import CSV beside Export and Add Product;
• POS Operations shows each operator’s shift limit;
• editing an operator persists a value between 15 and 720 minutes;
• opening a Till shift produces the configured server expiry; and
• signing the same operator into another device closes the earlier session.

Upgrade Android Tills

Upgrade Android only after the engine and dashboard are healthy. A host app that embeds ARR updates its Maven dependencies, rebuilds, tests, and distributes the new app through its normal device-management channel:

dependencies {
  implementation("com.withpotter.box:box-commerce:0.1.0-alpha.4")
  implementation("com.withpotter.box:box-arr-ui:0.1.0-alpha.4")
}

Demo Till users install the matching APK:

adb install -r box-demo-0.1.0-alpha.4.apk

The -r install preserves the app’s linked-device data. Verify a 60-minute idle lock, wrong PIN rejection, correct active-operator PIN resume, continued heartbeats while locked, and an unchanged server session ID.