Skip to content

Hosting: upgrades#

This documentation applies to Piler enterprise edition 2.2.5+

Revision #1

Publication date: 2026-OCT-25

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, set the new version (PILER_VERSION in the example's .env) and:

docker compose pull
docker compose up -d

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

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.