Skip to content

Hosting: onboarding a tenant#

This documentation applies to Piler enterprise edition 2.2.5+

Revision #1

Publication date: 2026-OCT-25

A checklist for a new customer, from DNS to the first archived email. The commands follow the multi-node example; on a single node, the steps marked multi-node don't apply.

Before you start#

Agree with the customer:

  • the tenant id: 3-64 lower-case letters, digits and _, e.g. customer1 (it becomes a database, an index and a bucket name). With S3 storage (also for Teams or Slack) no _: the bucket is S3_BUCKET_PREFIX + tenant id (Teams: TEAMS_S3_BUCKET_PREFIX + teams- + tenant id), at most 63 characters, and bucket names can't have _
  • the email domains to archive
  • the hostname of their archive, e.g. customer1.archive.example.com
  • the retention period
  • how the users log in: local accounts, LDAP / Active Directory, Entra ID, Google Workspace, IMAP
  • how the email gets to Piler: journaling from Microsoft 365, or a copy of every email from their mail server
  • the historical email to import, if any

1. Hostname and certificate#

  • Point the tenant's hostname at the master (the reverse proxy in front of piler-ui).
  • Get a certificate for it. In the example, add a router for the hostname to Traefik's traefik-dynamic.yaml (it gets its own Let's Encrypt certificate), or use a wildcard certificate for all tenants.

2. Storage#

  • With S3 storage, create the bucket S3_BUCKET_PREFIX + tenant id, e.g. customer1, before the tenant receives email. Piler doesn't create buckets: the tenant's emails sent before go to the error directory, to be moved back by hand (see buckets and permissions).

3. Create the tenant#

On the master, add the tenant in Admin > Tenant > Tenant: tenant id, domain, hostname (gui_url), archive address, retention, the tenant admin's password. Or with the REST API:

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
   -d '{"tenant_id":"customer1", "domain":"customer1.com",
        "gui_url":"customer1.archive.example.com",
        "archive_address":"customer1@worker0.example.com",
        "admin_password":"<password>", "retention_days":3650,
        "enable_purge":1, "settings_json":"{}"}' \
   https://archive.example.com/api/v1/admin/tenant/add
  • Multi-node: add the same tenant (same id, domain and hostname) on every worker too, through the worker's piler-ui on the private network (http://worker0.example.internal:3000/api/v1/admin/tenant/add).
  • The databases, indexes and directories are created by cron within 15 minutes on each node, or at once with docker compose exec piler su piler -c /usr/libexec/piler/create-tenant.sh.
  • Add the customer's other domains under Admin > Domain, mapped to the tenant's domain.

4. Look and login#

  • Optional: the tenant's logo and colors, Admin > Branding.
  • Set up the login: LDAP, Entra ID, Google Workspace, or local accounts.
  • Create the auditors. The tenant's admin@local administers the tenant but can't search email; auditors search everything, users their own email (see roles and permissions).

5. Email flow#

  • The archive address is <tenant id>@<worker hostname>: piler-smtp on a worker accepts only recipients at the hostname of its license. With several workers, spread the email among them (several MX records or a relay), each to its own worker's address.
  • Set up the journaling: Microsoft 365, or a copy of every email from their mail server. Envelope recipients keep the Bcc recipients.
  • Allow the customer's mail servers to reach port 25 of the workers, and nobody else (firewall or smtp_access_list).
  • Send a test email, and find it as an auditor.

6. History#

  • Import the earlier email: PST, EML, mbox or an IMAP mailbox, see import and the migration guides. Run the import on a worker.

7. Go live#

  • Check the tenant in monitoring: its received count grows, and the "journaling stopped" alert covers it.
  • Hand over: the archive's address, the tenant admin's login, the user guide.