Upgrading

This documentation applies to Piler enterprise edition 2.2.5

Revision #3

Publication date: 2026-OCT-21

This document describes how to upgrade from 1.8.4 to the latest 2.x version of piler enterprise.

It applies to single node, no-tenant deployments only, ie. a single host running all piler components with the single piler database.

Prerequisites

Real time index

Check with this command

mariadb -h0 -P9306 <<< 'show tables'
Table   Type
piler   rt
piler_audit1    rt
piler_cat1  percolate
piler_note1 rt
piler_tag1  rt

Upgrade steps

Fix permissions

chmod 750 /var/piler/store/
chmod 750 /var/piler/astore/

Stop the legacy piler components

systemctl stop piler
systemctl stop piler-smtp
systemctl stop nginx
systemctl stop php8.3-fpm

Install piler 2.x

curl -fsSL https://packages.mailpiler.com/piler-ee.gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/piler-ee.gpg
echo "deb [signed-by=/etc/apt/trusted.gpg.d/piler-ee.gpg] https://packages.mailpiler.com/deb stable main" | tee /etc/apt/sources.list.d/piler-ee.list
apt-get update
apt-get install -y piler-ee redis
apt-get install -y piler-smtp
curl -L -s -o /etc/piler/license.pub https://download.mailpiler.com/license.pub

Reset crontab

The below command replaces the crontab of the piler user. If you have added your own entries to it, then save them first, and add them again afterwards.

crontab -u piler /usr/share/piler/cron.jobs-2.x

Write the piler config file

A minimal working /var/piler/.env file

LICENSE_FILE=/etc/piler/license.jwt
LISTEN_ADDR=127.0.0.1:3000
NODE_TYPE=master
MULTITENANCY=false
MYSQL_USER=piler
MYSQL_PASSWORD=piler123
MYSQL_HOST=localhost:3306

MANTICORE_DSN=piler:piler123@tcp(localhost:9306)/?parseTime=true
MANTICORE_READONLY_DSN=piler:piler123@tcp(localhost:9307)/?parseTime=true

REDIS_ADDR=localhost:6379

LANGUAGES=de,en,es,fr,zh

LOG_LEVEL=INFO
NOREPLY_EMAIL_ADDRESS=no-reply@archive.example.com

DATE_FORMAT=YYYY/MM/DD
TIMEZONE=Europe/Budapest

DIR_EXPORT=/var/piler/export

PILER_THREADS=3

ML_PHISHING_ENABLED=true
ML_PHISHING_THRESHOLD=0.5
SECURITY_RISK_ENABLED=true
COMPLIANCE_RISK_ENABLED=true
SCAN_RATE_LIMIT=1000
SMART_INSIGHTS_ENABLED=true
SCANNER_THREADS=2

SEMANTIC_SEARCH_ENABLED=false

# Run the below command to generate an encrypt key for imap import passwords
# < /dev/urandom tr -dc 'A-Za-z0-9' | head -c 32
IMAP_ENCRYPT_KEY=<generate me>

Semantic search is disabled by default. See Semantic search if you want to enable it after the upgrade.

Run the migrations

Run the mysql migrations on the piler database:

for i in /usr/share/piler/migrations/sql/*.sql; do
   mariadb --defaults-file=/etc/piler/.my.cnf piler < "$i" || break
done

Run the manticore migrations:

for i in /usr/share/piler/migrations/manticore/*.sql; do
   sed 's/TENANTID/piler/g' "$i" | mariadb -h0 -P9306 || break
done

Both loops stop at the first failing migration. Fix the reported error, then run the loop again, the migrations are safe to run more than once.

Add the participants column to the index. Piler 2.x refuses to start without it:

/usr/libexec/piler/add-participants-column.sh 0 --all

It's enough to run it once, but it's safe to run it again: it does nothing if the index has the column already. See Upgrading for the details.

Update the passwords

Piler uses the bcrypt password hashing algorithm, so the passwords in the local database must be fixed.

The below statement updates the built-in admin user's password to pilerrocks. After that let the admin reset other local users' passwords.

mariadb --defaults-file=/etc/piler/.my.cnf piler <<< 'update user set password="$2y$10$dEzUkJcI824suvEp4p.87u5IT7JitTzpMiMkBtOo7/RZvCYO5b8tC" where uid=1'

Copy the license file

Copy your license file to /etc/piler/license.jwt

Start piler 2.x

Reboot the host, and verify that all services come up properly.