Skip to main content

Upgrades

Procedure​

deploy/scripts/upgrade.sh 1.1.0               # backup, pull, migrate, rolling restart
deploy/scripts/upgrade.sh 1.1.0 --stop-first  # when the release notes say so

The script:

  1. takes a backup;
  2. sets RMM_VERSION in .env and pulls the images (skipped when RMM_SKIP_PULL=1, as the deploy workflow does);
  3. runs migrate up;
  4. starts as many new backends as are running, next to the old ones;
  5. stops the old ones once the new ones are healthy (agents reconnect to the new ones);
  6. migrates and restarts Entrosity Hub;
  7. recreates the portal container.

Upgrade drill (two backends, a request every 100 ms throughout): no failed API request during the backend phase; about 1 s gap while the portal container (the TLS terminator) was recreated; 16–18 s in total.

Schema checks​

A backend refuses to start against a schema it was not built for, for example:

  • "database is at version 9, this server needs 10; run migrate up";
  • "… newer than this server" after a downgrade attempt.

Migrations within a minor release are additive, so old backends keep working during the rolling restart. A release whose migration is not backward compatible says so in its notes; use --stop-first.

A dirty migration​

If a migration failed half-way (migration N failed half-way):

  1. fix the cause;
  2. docker compose -f docker-compose.prod.yml --env-file .env run --rm migrate force <N-1>;
  3. run upgrade.sh again.

Downgrades​

Migrations are not reversed in production:

  1. restore the backup taken by upgrade.sh with restore.sh, with RMM_VERSION set to the previous version;
  2. re-apply .env.bak if the upgrade changed it.

migrate down exists for development only.

Agent and connector compatibility​

ServerAgents / connectors
1.x1.0.0 and newer (protocol /v1; additive changes only)
  • Agents and connectors update themselves (Agent releases).
  • RMM_MIN_AGENT_VERSION makes anything older take the newest release at once. Set it after a security fix, or before a server release drops support for old agents.
  • The server never refuses an agent because of its version (that would cut off its update path); agents that cannot update keep working as long as the server supports their protocol version.