Skip to content

Installing piler enterprise edition#

This documentation applies to Piler enterprise edition 2.1.0+

Revision #5

Publication date: 2026-NOV-02

Installing on a single node using docker compose#

The recommended way: see Install on a single host, from an empty host to an archive receiving the journal of your mail server.

Installing on a single Linux node#

Download the installer script, customise the following variables:

  • PILER_HOSTNAME
  • MYSQL_ROOT_PASSWORD
  • MYSQL_PILER_PASSWORD
  • ARCH (either "amd64" or "arm64")

Execute the installer

curl -o install.sh https://download.mailpiler.com/install.sh
chmod +x install.sh
sudo ./install.sh

Copy the license file to /etc/piler/license.jwt, then reboot the host, and verify that all services come up properly.

Centos/Redhat/Oracle Linux specific notes#

SELinux needs to be disabled.

Backup#

From 2.3.0 the package has /usr/libexec/piler/piler-backup.sh: a daily backup into a restic repository of the databases, the search index, the stored emails and attachments, /etc/piler (the settings, piler.key, the license) and /var/piler/.env. Use it if your backup system doesn't cover piler already, see large deployments: backup for what to back up. It needs restic (apt install restic; on Oracle Linux and RHEL from EPEL).

cp /etc/piler/backup.env.dist /etc/piler/backup.env
chmod 600 /etc/piler/backup.env

Set BACKUP_REPOSITORY (s3:https://host/bucket/path, sftp:user@host:/path, rest:https://host/path, or a directory on another disk) and BACKUP_PASSWORD in it. Keep a copy of the password off the host: without it there's no restore. Then, as root:

/usr/libexec/piler/piler-backup.sh                 # a backup now
/usr/libexec/piler/piler-backup.sh snapshots       # the backups

With a directory, create the repository first, with BACKUP_INIT=1 /usr/libexec/piler/piler-backup.sh: later backups don't create one, so a disk that isn't mounted makes the backup fail instead of filling the host's disk.

Nothing runs it by default. To back up every day, e.g. /etc/cron.d/piler-backup:

30 2 * * * root /usr/libexec/piler/piler-backup.sh >> /var/log/piler-backup.log 2>&1

It logs in to MariaDB as root with /root/.my.cnf (the installer writes it), which must be root's. A store outside /var/piler (PILER_STORE_DIR, PILER_ASTORE_DIR) goes into BACKUP_STORE_PATHS of backup.env, on the host you restore to too. With Manticore on another host, set BACKUP_MANTICORE=no and back up the index there.

A backup doesn't start while another one runs. It stops if MariaDB isn't running; without Manticore it backs up the rest, and a restore of it needs a reindex. Either way it's recorded as a failed backup: Admin > Health and the PilerBackup* alerts of the monitoring show it. On Sundays it frees the space of the removed backups and reads 5% of the data back to check it.

To restore on a new host: install the package, start MariaDB (root must log in, e.g. with /root/.my.cnf), put backup.env in place, then

/usr/libexec/piler/piler-backup.sh restore <id>
systemctl start piler-search piler piler-ui

It restores into an installation without piler.key and a piler database only. The emails archived after the backup are not in it. Emails in S3 storage aren't in the backup, see S3 object storage.

Installing on multiple Linux nodes#

In this setup you'll have 1 frontend node and 2 worker nodes. It's recommended to have an MX server that receives emails to be archived, and distributes them among the worker nodes.

The frontend node runs only the UI (it also needs mysql, manticore and redis). The worker nodes run all components. Each worker node shall have its own unique server id (eg. 00, 01, 02, ...) that comes from the license file.

The worker nodes hostnames are worker0.example.com and worker1.example.com

Installing the worker nodes#

Run install.sh just as shown above. Add these extra settings to /var/piler/.env:

MULTINODES=true
NODE_TYPE=worker
JWT_SECRET=<your secret>

Generate the JWT secret once, e.g. with openssl rand -hex 32, and use the same one on all nodes. Don't copy a value from an example.

Installing the frontend node#

Run install.sh just as shown above. Add these extra settings to /var/piler/.env:

MULTINODES=true
WORKERS=http://worker0.example.com:3000,http://worker1.example.com:3000
JWT_SECRET=<your secret>

Notice that the JWT secret is the same as on the worker nodes.

Stop and disable the following services:

  • piler
  • piler-smtp
  • scanner
  • tika
systemctl stop piler
systemctl disable piler
....

Installing the MX server#

You may use postfix, etc. as the MX server. See the examples repo for a working setup.

Security considerations#

  • the worker nodes need to access mysql on the frontend node
  • the frontend node needs to access port 9312 on the worker nodes
  • the UI port (3000) of the worker nodes shall be accessed only from the frontend node
  • the SMTP port (25) of the worker nodes shall be accessed only from the MX server
  • you need a reverse proxy like traefik or nginx on the frontend node to provide https access