Docs Installation 4
Upgrades
On this page
A release changes the application; the plant's designs live in its database and change only through change requests, so an upgrade leaves them as they are. The database upgrades itself: at each start, every new or changed migration runs, in order, under one lock (several instances starting together run each once). Migrations go forward only.


IN-40Upgrade a server
| Purpose | A new release, with its database changes, and a way back. |
|---|---|
| Done by | IT |
| Before you start |
|
| # | Do this | You should see | Done |
|---|---|---|---|
| 1 | Make a backup now, and note its file name: it is the way back (IN-42).systemctl start opencore-mes-backup.service ls -lt /var/backups/opencore-mes | head -3 | The newest opencore_mes-<stamp>.dump.enc. | |
| 2 | Install the new release beside the current one: IN-12 steps 1 to 3, with its own folder name (not step 4 yet). | — | |
| 3 | Optionally, the test pipeline in the new release (IN-21 step 2, in its folder). | all … stages passed. | |
| 4 | Switch to it, and restart.ln -sfn /srv/opencore-mes/releases/<new build> /srv/opencore-mes/current
systemctl restart opencore-mesCannot be undone. Once it has started, the new release's migrations have changed the database, and they go forward only: the previous release cannot run on it again. The way back is the backup of step 1 (IN-42). | — | |
| 5 | A release that brings a new version of the search index (the first, 2026-10-14: over the records' values alone) rebuilds it at its first start, on every object's records: writes to records wait for the build, about a minute at a million records (more on a plant's disk); reads go on; the old index is dropped once the migration is done, a moment every read and write waits for. A plant that cannot pause writes pre-builds it per partition before the switch (ops/db/README.md, The search index), and the start then skips the rebuild. | database: applied search-text in the journal, once. | |
| 6 | With several instances: restart them one at a time, those that read a replica (REPLICA_URL) first.Cannot be undone. An older instance reading a replica cannot follow a change the new build publishes without a log position ( app/mes/README.md, Several instances). | Each comes back on the new build while the others keep serving. | |
| 7 | See what migrated, and ask it how it is.journalctl -u opencore-mes -n 50 -o cat curl -fsS http://127.0.0.1:3000/healthz | database: applied … for each migration (the event db.migrated names them); ok true; the new build. | |
| 8 | If the trail is protected and the release notes say a migration changes it: run that migration and the protection script as postgres (IN-17). | — | |
| 9 | The first upgrade to a release with the data integrity review: an integrity reviewer opens Design → Data integrity and signs Take the baseline. | From then on a change made around the platform is found. | |
| 10 | The first upgrade to a release that executes changes by hand (2026-10-17): from now on an approved change waits for the executor named at its submission to press Execute, then verify it, unless People & departments says otherwise. Every designer was given the executor role. Tell the designers; a plant that wants changes live at the last signature, as before, clears Execution (People & departments → Approvals) through a change governance approves. | Approved changes wait on Approvals as execute it; a change approved before the upgrade and waiting for a peer executes as before. | |
| 11 | Keep the last few releases in /srv/opencore-mes/releases; remove older ones. | — |
IN-41Upgrade a plant folder (npm)
| Purpose | A new version of the npm package. |
|---|---|
| Done by | IT |
| # | Do this | You should see | Done |
|---|---|---|---|
| 1 | Make a backup first (IN-18 step 5, or backup.sh by hand), and stop the server (Ctrl+C, or its service). | — | |
| 2 | Install the new version.npm install -g @opencore-mes/server@<version>
opencore-mes version | The new version. | |
| 3 | From inside the plant folder: bring the database up to date (or let the start do it).opencore-mes db migrate Cannot be undone. The database's changes go forward only: the previous version cannot run on it again. The way back is the backup of step 1. | What migrated, or database: up to date. | |
| 4 | Start it.opencore-mes start | listening on …; /healthz answers. |


IN-42Going back after a bad upgrade, or restoring a backup
| Purpose | The previous release running again, on the data as it was before the upgrade. |
|---|---|
| Done by | IT, with the plant's agreement |
| # | Do this | You should see | Done |
|---|---|---|---|
| 1 | If the new release never started (its migrations did not run): point current back at the previous release, and restart. Then stop here.ln -sfn /srv/opencore-mes/releases/<previous build> /srv/opencore-mes/current
systemctl restart opencore-mes | The previous build in /healthz. | |
| 2 | Otherwise its migrations have changed the database, and the previous release cannot be pointed at it. Stop the service.systemctl stop opencore-mes | — | |
| 3 | Give the service's user the backup taken before the upgrade, its checksum and the key, for the restore only.install -d -m 0700 -o opencore /var/lib/opencore-mes/restore install -m 0400 -o opencore /var/backups/opencore-mes/<file>.dump.enc /var/backups/opencore-mes/<file>.dump.enc.sha256 /etc/opencore-mes/backup.key /var/lib/opencore-mes/restore/ | — | |
| 4 | Restore it into a new database, as the service's user (so the service owns it, as it owned the old one); then remove the copies.cd /srv/opencore-mes/current sudo -u opencore env PGHOST=/var/run/postgresql BACKUP_KEY=/var/lib/opencore-mes/restore/backup.key TARGET_URL=postgres:///opencore_mes_<date> ops/backup/restore.sh /var/lib/opencore-mes/restore/<file>.dump.enc rm -rf /var/lib/opencore-mes/restore Cannot be undone. The last line removes only the copies made in step 3; the backups in /var/backups stay. | Checksum checked, restored, and its audit chain verified (verify-audit.mjs --full). It refuses a target that exists. | |
| 5 | Open the settings file and point DATABASE_URL at postgres:///opencore_mes_<date>; save and leave.nano /etc/opencore-mes/opencore-mes.env | — | |
| 6 | Point current at the previous release, and start.ln -sfn /srv/opencore-mes/releases/<previous build> /srv/opencore-mes/current
systemctl start opencore-mesCannot be undone. Everything recorded after the backup was taken is not in the restored database. Keep the upgraded database aside: it is the only place those records remain. | The previous build, on the data of the backup. | |
| 7 | Tell the plant what is lost: everything recorded between the backup and the stop. Run the protection script on the restored database (IN-17, with its name), and keep the upgraded database aside until it is no longer needed. | — |
Caution. There is no rollback command: going back is this procedure. A backup before every upgrade is what makes it possible.