Skip to main content
Version: 3.0 (next)

Upgrade from 2.6.x to 3.0

3.0 stores its data differently from 2.6, so your existing data is migrated once, by a command you run. MaestroHub never migrates data on its own.

This guide has five steps. Each step shows the command, what it prints, and what to do for each result it can give. Go to the next step only when the step says so.

StepWhat you doMaestroHub is
1Get 3.0Running on 2.6
2upgrade check: see what will changeRunning on 2.6
3Stop MaestroHubStopped
4upgrade apply: back up and migrateStopped
5Start 3.0Running on 3.0

Until step 5, you can put everything back as it was with one command (see Go back to 2.6).

Is this guide for you?​

You runWhat to do
2.6.0 to 2.6.5 with Docker Compose, docker run or the single binaryFollow this guide.
A release older than 2.6.0Upgrade to 2.6.x first, then follow this guide.
2.6 on Kubernetes (Helm)There is no upgrade path. Contact MaestroHub support before you upgrade. See Kubernetes.
No existing dataInstall 3.0. There is nothing to upgrade.

Which version do you run? Ask MaestroHub itself: the tag in your Compose file or command line is not proof, because an image can be re-tagged. Every 2.6 release answers, without signing in:

docker compose exec maestrohub wget -qO- http://localhost:8080/api/v1/version

It prints, for example, {"version":"2.6.5",…}. With docker run, use docker exec <container name> in place of docker compose exec maestrohub. From a browser, open /api/v1/version on the address you use for MaestroHub (on the single binary, http://localhost:8080/api/v1/version).

Before you start​

Do these four things first. The first three cannot be made up for afterwards.

  1. Export history older than 32 days, if you need it. 3.0 keeps at most 32 days of history, and its first start deletes older values. The upgrade's backup does not hold history. See History is capped at 32 days.
  2. Back up your external databases. The upgrade backs up MaestroHub's own file-based stores. It does not back up an external TimescaleDB, or any store you keep in PostgreSQL. See Backup sets.
  3. Plan your own copy of MaestroHub's data. The upgrade's backup takes you back to 2.6 only until 3.0 has started. A problem you find after that — for example a pipeline that needs your edit (see If items need your OK) — can only be undone from a copy of your own. Step 3 shows how to take it. On a virtual machine, a snapshot of its disk does the same.
  4. Read What Changes in 3.0. A table at the top shows which changes affect you. Two reach outside MaestroHub: UNS topic paths gain the organization, and the shared uns_reader MQTT login is removed. Systems that connect over MQTT need to follow.

Plan the downtime. MaestroHub is stopped from step 3 until step 5. The first start of 3.0 can also take longer than usual on a large installation. The report in step 2 tells you how long.

Working over SSH? Run steps 3 to 5 inside tmux or screen, so that a dropped connection does not cut apply off. If it does, see If apply was cut off.

How to run an upgrade command​

Every upgrade command is the same on every installation. Only the part in front of it differs: the prefix that runs it in your kind of installation.

docker compose run --rm maestrohub maestrohub-lite  upgrade check  --config /config/config.yaml
#└──────────────── prefix ───────────────────────┘  └─ command ─┘  └──────── flags ─────────┘

This is for the 2.6 marketplace bundle, where the service is named maestrohub and its command: line starts with maestrohub-lite --config /config/config.yaml. If your Compose file differs, use your own service name, and the command from your own command: line. If your service has no command: line, leave out maestrohub-lite and --config /config/config.yaml. docker compose config --services lists your service names.

Run every command from the folder that holds your Compose file. Two more things can differ:

  • Your Compose file has another name than the default ones (compose.yaml, docker-compose.yml and their .yml/.yaml variants), for example docker-compose.prod.yaml. Name it once in each shell, export COMPOSE_FILE=docker-compose.prod.yaml, or put -f docker-compose.prod.yaml after docker compose in every command of this guide.

  • A reverse proxy reads your containers' labels (Traefik, for example). Each upgrade command runs in a one-off copy of the maestrohub service, and that copy has the service's labels. While 2.6 still serves users (step 2), keep the proxy from routing to it: put -l traefik.enable=false after run --rm.

    docker compose run --rm -l traefik.enable=false maestrohub maestrohub-lite upgrade check --config /config/config.yaml
Keep your 2.6 Compose file

Change only the version. Do not switch to the Compose file that ships with the 3.0 bundle: it uses a different volume name, so 3.0 would start on a new, empty volume instead of your data.

Step 1. Get 3.0​

First keep a copy of your Compose file and .env as they are now: you put them back if you go back to 2.6.

cp docker-compose.yml docker-compose.yml.2.6    # your Compose file's name
cp .env .env.2.6                                # if you have one

Set LITE_VERSION=<3.0 version> in .env, or change the tag in image:, for example to maestrohub/lite:3.0.0. Change nothing else. Always give the exact version: maestrohub/lite:latest stays on 2.6.5 (see Image and command names). Then pull the image:

docker compose pull maestrohub

Offline, load the 3.0 image archive instead: docker load -i <archive>. The archive carries both image names, so your Compose file finds it.

Do not run docker compose up yet. 2.6 keeps running on the old image until step 3.

Step 2. Check​

upgrade check runs the whole upgrade on a copy of your data and prints a report. It changes nothing. 2.6 can keep running.

docker compose run --rm maestrohub maestrohub-lite upgrade check --config /config/config.yaml

What it prints​

A short summary. It takes a few seconds to a minute.

Reading the stores (11) …
Checking what the upgrade will do …
Checking items … 10,000
MaestroHub upgrade check · data from an earlier version → 3.0.0

  Will convert      47,012 items (37,751 changes made automatically)
  Database changes  87 migrations
  Needs your OK     25 items: 13 with a proposed change, 2 with one for part of it, 10 to edit by hand afterwards
  Stores            11 move to the new layout · 1 copied out of PostgreSQL
  First start       under a minute of extra work
  Good to know      658 notes · 25 old config settings · 1 security warning
  MaestroHub        is running: stop it before apply
  ! Security: encryption keys are publicly known (1 warning). Rotate them after the upgrade: --show warnings

Next: stop MaestroHub, then run
  docker compose run --rm maestrohub maestrohub-lite upgrade apply --config /config/config.yaml
  It asks before it changes anything.
  In a script: add --accept-all --force

Details:  --show needs-a-person | notes | warnings | stores | all
LineWhat it tells you
Will convertHow many stored items (pipelines, topics, dashboards and so on) the upgrade converts on its own.
Needs your OKItems the upgrade cannot decide alone. apply asks you about them in step 4. See If items need your OK.
StoresStores that apply moves to where 3.0 keeps them.
First startExtra time the first start of 3.0 needs. Plan for it.
Good to knowNotes about behaviour that changes, and warnings. Most warnings are old settings in your config.yaml that 3.0 no longer reads; they do not stop the upgrade.
MaestroHub is runningExpected at this step. You stop it in step 3.
! SecurityA secret is protected by a key that is publicly known. The upgrade still runs. Rotate the key afterwards: --show warnings says how.

To read any part in full, run the same command again with --show and the part's name, for example --show notes. --show all prints everything.

What to do next​

The summary saysWhat it meansWhat to do
Next: stop MaestroHub, then run … upgrade applyThe upgrade can run.Go to step 3.
A line Needs your OKThe upgrade can run, and will ask you about those items.Read them first: see If items need your OK. Then go to step 3.
A block Stops the upgradeSomething stands in the way, for example an item that cannot be read. No apply command is printed.Do what each line says, then run check again.
Nothing to do: every store is at 3.0.0.The data is already at 3.0.Go to step 5.
Not upgraded: followed by an errorThe check itself could not run, for example because the config file was not found.Fix what the error names, and check again.

If items need your OK​

These are places where the right change depends on what the author meant, for example a script that reads a topic path segment by its position. The upgrade does not change them without your yes.

To read them, add --show needs-a-person to the check command. For each item it prints either a proposed change, before and after, or the reason there is none:

  pipeline "Shift Counter" · org default
    node "Hierarchy" › parameters.code
      11:27 compares the number of segments of the topic path with 3; 3.0 paths carry the organisation, so what was at 3 is at 4 now.
      proposed:
        - 11 | const op = parts.length > 3 ? parts[3] : null;
        + 11 | const op = parts.length > 4 ? parts[4] : null;

Then choose:

  • Accept them. You do this in step 4: apply asks you. A proposed change is written. An item with no proposal stays as it is, for you to fix in the editor after the upgrade.

    An item with no proposal keeps running

    Until you fix it, it runs on 3.0 with its 2.6 code. In an enabled pipeline, that code can read nothing where 2.6 gave it a value, so the pipeline publishes wrong values, or nothing, while every run shows as completed. Before step 4, write down which of these pipelines are enabled. Fix them right after step 5, and check the values they publish, not only their run status. To stop one from running meanwhile, disable it on 2.6 before step 3.

  • Fix the items on 2.6 first, then run check again until the line is gone. 2.6 still runs your change, so write it to work on both versions: for example, read out.result ?? out.records instead of only out.result, and find a topic path segment by its name instead of by its position. If check still lists an item after such a change, accept it.

3.0 does not start until every item is decided. To accept only some of them, see Items that need a person.

Step 3. Stop MaestroHub​

docker compose stop maestrohub

Then check that it is stopped:

docker compose ps

The maestrohub service must not be listed as running.

If you keep MaestroHub stores in PostgreSQL, take a snapshot of that database now, while MaestroHub is stopped. apply asks for the snapshot's name in step 4.

Copy MaestroHub's data​

Take your own copy of MaestroHub's data now, while it is stopped. Until 3.0 starts, the upgrade's own backup can take you back; after that, only this copy can (see Go back after 3.0 has started). On a virtual machine, a snapshot of its disk does the same.

docker compose run --rm --no-deps -T --entrypoint tar maestrohub czf - -C /data . > maestrohub-data-2.6.tgz

This runs tar in the image from step 1, on the volume your Compose file mounts at /data, and writes the archive into the current folder. It needs about as much free disk as the volume holds.

Step 4. Apply​

upgrade apply asks what it needs to know, takes a backup of every store it changes, migrates your data, and verifies the result. If any step fails, it puts every store back as it was. Over SSH, run it inside tmux or screen (see If apply was cut off).

docker compose run --rm maestrohub maestrohub-lite upgrade apply --config /config/config.yaml

The questions it asks​

apply asks up to four questions, and changes nothing until the last one is answered. For a [Y/n] question, press Enter or type y for yes, and type n for no. A no stops apply with your data as it was.

1. Is MaestroHub stopped? You see this after every 2.6 installation, because 2.6 leaves some files beside its stores when it stops.

MaestroHub looks stopped. The earlier version leaves its stores' side files behind, so this cannot be checked from here.
  Is MaestroHub stopped?  [Y/n]

Check that it is stopped (step 3) before you answer yes. If apply can see that MaestroHub is still running, it does not ask: it stops and tells you.

2. Only if the upgrade changes a store you keep in PostgreSQL:

The upgrade changes one database it cannot back up: authz (db/authz).
  Name of the snapshot you took of it:

Type the name of the snapshot you took in step 3. apply records it with the backup, so you know which snapshot goes with this upgrade. With no name, apply stops.

3. Only if items need your OK:

25 items need your OK
  13 have a proposed change, which will be written.
  2 have a proposed change for part of it. The rest stays as it is, for you to edit afterwards.
  10 have none. They stay as they are, for you to edit afterwards.
  `upgrade check --show needs-a-person` lists them.
  Accept them?  [Y/n]

4. Always:

Ready. A verified backup (300.0 MiB) is written first, to
  /data/data/upgrade-backups/upgrade-20261001T090620Z-922f03
  Then 11 stores move to this release's layout.
  Start the upgrade?  [Y/n]

What it prints​

Writing the backup …
Running database changes …
Converting items … 10,000 of 47,037
Moving 11 stores to the new layout …

  ok  backup written and verified (300.0 MiB)
  ok  stores: 11 moved to the new layout · 1 copied out of PostgreSQL
  ok  87 database migrations run
  ok  47,037 items converted (25 accepted by you)

Upgraded and verified.
  To undo (only until the new version starts):  docker compose run --rm maestrohub maestrohub-lite upgrade restore --config /config/config.yaml --backup /data/data/upgrade-backups/upgrade-20261001T090620Z-922f03 --force
  Full report:  /data/data/upgrade-backups/upgrade-20261001T090620Z-922f03/report.txt
  First start: under a minute of extra work.
  Next: start MaestroHub.

Copy the To undo line and keep it. It is the command that takes you back to 2.6. The Full report file lists every change that was made.

What to do next​

The last lines sayWhat it meansWhat to do
Upgraded and verified.The data is migrated.Go to step 5.
Not upgraded: nothing was changed: …You answered no to a question, or apply found something in its way. The message says which.Do what the message says, then run apply again.
Not upgraded: … no answer came on standard input … Run with --forceThere was no terminal to ask on, for example docker run without -it.Run it in a terminal. For a script, see In a script.
Two lines: an error about a flag, then Run `… upgrade apply --help` for its flagsA flag is misspelled or has a wrong value. apply did not start.Correct the flag and run it again.
Upgraded, but not finished: MaestroHub does not start until every item is decided.Items that need your OK were left undecided. Everything else is migrated.Run apply again and accept them.
Not upgraded: with another errorA step failed, and every store was put back as it was.Read the error. If it names a PostgreSQL store whose changes were already committed, put that database back from your snapshot. Then fix the cause and run apply again.

Every message that says nothing was changed means exactly that: your data is as it was, and it is safe to run apply again.

If apply was cut off​

If apply stopped part way without finishing — the SSH connection dropped, the machine restarted, the process was killed — it left a record of the run beside its backup set, as soon as it had begun to change anything. Then:

  1. Do not start MaestroHub. 3.0 would refuse anyway: it shows the Upgrade needed page with the command that restores the backup.
  2. Run upgrade status. It says that the run was interrupted, and prints the restore command for that run's backup set. If it says Not upgraded yet: run upgrade apply. instead, the run was cut off before it changed anything: run apply again.
  3. Run that restore command. It puts back every store the run had started on.
  4. Run apply again. Until the restore is done, apply refuses.

In a script​

Where nobody can answer, give the answers as flags. check prints the flags your installation needs under In a script:

docker compose run --rm -T maestrohub maestrohub-lite upgrade apply --config /config/config.yaml \
  --accept-all --data-not-in-use --db-snapshot-taken my-snapshot-2026-10-01 --force
FlagThe question it answers
--data-not-in-useIs MaestroHub stopped?
--db-snapshot-taken <name>Name of the snapshot you took
--accept-allAccept the items that need your OK?
--forceStart the upgrade?

Step 5. Start 3.0​

docker compose up -d maestrohub

Name the service: a bare docker compose up -d also starts or recreates every other service whose definition or local image changed.

What you see​

Open MaestroHub in your browser, at the address you used before.

You seeWhat it meansWhat to do
The sign-in page3.0 is running on your data.Sign in with your 2.6 account. You are done. Go to After the upgrade.
Nothing yet: the page does not load3.0 is doing its first-start database work. On a large installation this takes minutes.Wait. The log shows progress every 15 seconds. Do not stop or restart it: the work would start over.
An Upgrade needed pageThe data is not migrated: step 4 did not finish. 3.0 changed none of your data.Stop MaestroHub (step 3), then go back to step 4. If apply was cut off, see If apply was cut off.

To check where you stand​

At any time with MaestroHub stopped, upgrade status says whether the data is ready, and lists the backup sets:

Ready for 3.0.0: every store is upgraded.
  Backup set  upgrade-20261001T090620Z-922f03 · 300.0 MiB · can still be restored
              holds secrets stored in plain text before the upgrade: delete it once MaestroHub runs well

If it says Not upgraded yet: run upgrade apply., do not start 3.0: go back to step 4.

After the upgrade​

  • Check that it runs as it did on 2.6. The same connections connect, the same pipelines run without new failures, and dashboards show live values. Under System → Upgrades, a platform administrator sees the upgrade's report and what it left to act on.
  • Fix the items that had no proposed change, starting with enabled pipelines. They were left as stored for you to edit, and they run with their 2.6 code until you do. System → Upgrades lists them. After each fix, check the values the pipeline publishes: a run that completes can still publish wrong values, or none.
  • Check the systems that read MaestroHub over MQTT. UNS topic paths now carry the organization (see UNS topic paths include the organization). A client still subscribed to the 2.6 paths receives nothing.
  • Expect some warnings in the log. A few warnings after the first start are normal. Warnings after the upgrade lists them.
  • Then delete the backup set. It holds your data as it was on 2.6, including secrets that 2.6 stored in plain text. upgrade status prints the command that deletes it. See Backup sets. The same goes for your own copy from step 3: it holds the same secrets, so keep it as protected as the data itself, and delete it once you no longer need a way back.

The upgrade is recorded in the audit trail at the first start, as an upgrade.applied event.

If you want to go back​

You can return to 2.6 with the upgrade's backup until 3.0 has started on the migrated data (step 5). Keep MaestroHub stopped and run the To undo command that apply printed. Then put back your 2.6 Compose file and .env from step 1 (or set the tag back to your 2.6 version), and start MaestroHub. Without that, it starts 3.0 on the restored data and shows the Upgrade needed page. See Go back to 2.6.

Once 3.0 has started, the To undo command refuses and changes nothing. You go back from the copy you took in step 3: see Go back after 3.0 has started.

Kubernetes​

There is no upgrade path for a 2.6 Helm installation. 3.0 on Kubernetes is a fresh installation: install it with its Helm chart. If you run 2.6 on Kubernetes, contact MaestroHub support before upgrading.

The 3.0 chart is the single-node chart, context-engine-single-node (deployment/context-engine/single-node/helm). It runs the maestrohub/context-engine image, and its README has the install steps.

More​