Skip to content

Hosting: upgrades#

This documentation applies to Piler enterprise edition 2.3.0+

Revision #3

Publication date: 2026-NOV-02

How to upgrade a multi-tenant deployment. The version specific steps of each release are in upgrading; this page is the order and the routine around them.

Before the upgrade#

  • Read the changelog and the upgrade notes of every version between yours and the new one. New versions and security fixes are listed in the changelog.
  • Try the new version on a test deployment, e.g. the example with a test tenant.
  • Take a backup of every node (see backup).
  • Tell the customers about the window: search and the web UI may be unavailable for minutes. No email is lost: the mail servers queue what a worker doesn't accept while it restarts.

The order#

  1. The workers, one at a time. While a worker restarts, the others keep archiving, and the master's search leaves out its emails for those minutes.
  2. The master (and the other UI nodes, if any), last.

On each node, in the directory of the example, run piler-upgrade.sh with the new version:

piler-upgrade.sh 2.2.6

It shows the upgrade notes since the node's version, asks before it does anything (on the master: if the workers are upgraded), pulls the images, dumps the node's database and copies .env into backups/, sets PILER_VERSION, and starts the new containers and waits until they're healthy. By hand: set PILER_VERSION in .env, then docker compose pull and docker compose up -d --wait.

Migrations#

Some releases change the database or the index. The upgrade notes say when, and the release's migrations go:

  • MariaDB: on every node, for the piler database and every tenant's database.
  • Manticore: on the workers (or the single node), for every tenant. Not on the master: its tenant tables are distributed tables, the workers hold the data.

A loop over the tenants, in a node's piler container:

for t in piler $(mariadb --defaults-file=/etc/piler/.my.cnf -N piler -e "SELECT tenant_id FROM tenant_settings WHERE tenant_id != 'piler'"); do
   for f in /usr/share/piler/migrations/sql/*.sql; do
      mariadb --defaults-file=/etc/piler/.my.cnf "$t" < "$f"
   done
done

piler-upgrade.sh stops piler, piler-ui, the scanner and s3uploader (piler-smtp keeps taking the email), then runs all the migrations of the new version before it starts the new containers, on every database of the node, the Manticore ones not on the master. The migrations are safe to run again, so one you skipped in an earlier upgrade is run too. A failed one stops it, with the old containers running.

The Docker images run some of these steps themselves at start; the upgrade notes say which.

After the upgrade#

  • Check the version on each node: piler logs it at start (docker compose logs piler | grep "is starting"). Admin > Health on the master shows the status of the workers.
  • Check the monitoring: every piler-ui up, every tenant's received count growing.
  • Search a recent email of a tenant on each worker.