Skip to content
ManabloxManabloxManablox Guide

Updating Manablox

New Manablox versions bring fixes, security updates and new features. Updating is the same few steps every time: make a backup, raise the version numbers in package.json, rebuild, start. The database is updated automatically when the CMS starts.

How versions work

Section titled “How versions work”

Your CMS is made of five @manablox/* packages, listed in package.json:

"dependencies": {
  "@manablox/admin": "^0.18.0",
  "@manablox/cli": "^0.18.0",
  "@manablox/core": "^0.18.0",
  "@manablox/fields": "^0.18.0",
  "@manablox/server": "^0.18.0"
}

They are released together, always with the same version number. Keep all five on the same version: update them together, never one alone.

package.json holds a version range (the ^ means “this version or a compatible newer one”). The exact versions that get installed are recorded in pnpm-lock.yaml. That is why the lockfile has to be written again after every change.

To see the newest version, look up @manablox/cli on npmjs.com, or ask npm from the server (this runs npm in a temporary Node.js container, so it needs only Docker):

Terminal window
docker run --rm node:24-bookworm-slim npm view @manablox/cli version

Before you update

Section titled “Before you update”

Read what changed between your version and the new one, especially changes that need you to do something. While Manablox is in the 0.x versions, a change in the second number (for example from 0.18 to 0.19) can include such changes.

Then make a backup, so you can go back if something goes wrong:

Terminal window
./scripts/backup.sh

Also keep a copy of the two files you are about to change:

Terminal window
cp package.json package.json.before-update
cp pnpm-lock.yaml pnpm-lock.yaml.before-update

See Backups for what the backup contains.

Update a docker project

Section titled “Update a docker project”

Run these steps in your project folder on the server.

  1. Open package.json (for example with nano package.json) and change the version of all five @manablox/* packages to the new one, for example from ^0.18.0 to ^0.19.0. Leave typescript and @types/node as they are.
  2. Write the lockfile again. The script runs pnpm in a temporary container:
Terminal window
./scripts/lockfile.sh
  1. Build the new image:
Terminal window
docker compose build
  1. Start it:
Terminal window
docker compose up -d
  1. Watch the logs until the admin is back:
Terminal window
docker compose logs -f migrate api

Compose runs the migrate service first. It brings the database tables up to date for the new version and then stops. Only when it has finished successfully do api and public start again. So a migration problem stops the update before any visitor sees a half-updated CMS.

You should see migrate finish and api start. docker compose ps should show api as (healthy) again after about half a minute. Open the admin and check that you can sign in and see your content.

If you keep the project in Git, commit the new package.json and pnpm-lock.yaml.

Update a local project

Section titled “Update a local project”

On your computer, with a project made with the local preset:

  1. Change the five @manablox/* versions in package.json, as above.
  2. Install them:
Terminal window
pnpm install
  1. Update the database:
Terminal window
pnpm migrate
  1. Stop pnpm dev with Ctrl+C if it is running and start it again.

Instead of editing package.json by hand you can let pnpm do it. This moves every @manablox/* package to the newest version and updates package.json and the lockfile:

Terminal window
pnpm update "@manablox/*" --latest

Run pnpm migrate afterwards in any case.

Your website

Section titled “Your website”

Your website is a separate project. If it uses @manablox packages (for example @manablox/public-sdk), update them there the same way, then build and deploy the website again.

If something goes wrong

Section titled “If something goes wrong”

First look at the logs:

Terminal window
docker compose logs migrate api

If migrate failed, api does not start, and the message in the migrate log says why. Common problems covers the usual causes.

If you cannot fix it and need to go back to the old version:

  1. Put the old files back:
Terminal window
cp package.json.before-update package.json
cp pnpm-lock.yaml.before-update pnpm-lock.yaml
  1. Build the old image again:
Terminal window
docker compose build
  1. Restore the backup you made before the update (use the folder name backup.sh printed):
Terminal window
./scripts/restore.sh backups/2026-09-11_03-00-00

The restore is needed because database updates only go forward: there is no command that undoes them, so the backup is your way back to the old database. The restore puts the database and the uploads back to the moment of the backup, then starts the CMS again with the old version.