MAILFLOW · AUTOMATED REPORTING

Automate your reporting. Let MailFlow handle the rest.

Turn recurring reports into a fully automated workflow. MailFlow brings live data, tables, charts and spreadsheet or PDF attachments together, then delivers each report by email on the schedule you choose. This handbook takes you from a one-file offline installation to your first sign-in and everyday use—without burying you in technical detail.

1 fileoffline setup
Offlineno internet on the server
Automaticscheduled delivery
Hourlybackups, from day one
Business datalive source Spreadsheetslive source Other data sourcesconnect what you use MailFlow XLSX PDF {{date}} tables · charts · attachments your schedule email delivery recipients Delivery status 8 sent1 retrying1 bounced tracked for each recipient
NEW SETUPSet up MailFlowWhat you need, one-file installation, and your first sign-in.Start here ↓ FIRST DAYGet ready to sendSign in, secure the admin account, and complete the short readiness checklist.First-day guide ↓ EVERYDAY USEKeep MailFlow runningCheck status, review activity, protect your data, and make routine changes.Operations guide ↓ ADMIN REFERENCEMaintain or recoverUpgrades, restore, troubleshooting, configuration, and the quick reference.Admin guide ↓
THE MAILFLOW PROMISE

Set it up once. Let the routine take care of itself.

MailFlow turns the reports you repeatedly prepare and send into a dependable, scheduled workflow.

01

Connect your data

Use the databases and spreadsheet-based sources your reports already depend on.

02

Design the report once

Combine written context with live tables, charts, and the attachments your recipients need.

03

Choose the schedule

MailFlow prepares and sends each report automatically, then keeps a record of the delivery.

Part I · Get to know MailFlow

01Meet MailFlow

Recurring reports, without the recurring work. Set the content and schedule once; MailFlow takes care of the routine delivery.

Authorised users compose rich HTML emails in a Word-style editor, drop in live SQL-driven tables and charts, attach CSV, XLSX or PDF exports generated from SQL, and send them on a schedule through a corporate SMTP relay. Every send is recorded per recipient with the relay's own reply, so "did the finance list get the 08:00 report" is a lookup, not a guess. It replaces an older PHP + cron auto-emailer.

Your data stays where it is

MailFlow connects read-only to Oracle, PostgreSQL, EDB, MySQL, Trino and Teradata, natively or over JDBC/ODBC. Its own database holds only its own state: users, connections, queries, emails, schedules and the delivery ledger.

Everything configured in the UI

SMTP relays with failover chains, SFTP targets, LDAP, bounce mailboxes, housekeeping: all in the Control Panel, credentials encrypted at rest. No config file editing after install.

Two factors for everyone

Password (local or Active Directory) plus an authenticator-app code. No self-registration: an admin creates each account first. Trusted devices skip the code for 12 hours.

Watches itself

A missed-run detector, per-recipient bounce tracking, a fleet overview of today's sends, and a System Monitor with host CPU, memory and disk. Failures notify the report's owner.

02What comes in the package

Everything needed for an offline installation is carried in one installation file. Nothing needs to be downloaded on the server.

mailflow-<version>.run 2.5 GB · sha256 inside · executable Stub POSIX sh, ~120 lines verifies the checksum unpacks to /var/tmp runs install.sh payload.tar.gz 3 container imagesbackend · web · postgres4.3 GB unpacked Scriptsinstall · uninstallmailflow-ctl · backup podman RPMs33 packages · 33 MBonly if missing Components (you choose)whisper turbo 1.6 GB · tiny 75 MBdemo warehouse · 38 queries · 9 emails
PieceWhat it is for
Container imagesMailFlow backend (Python/FastAPI, ~2.2 GB), MailFlow web (nginx serving the built UI and proxying the API), PostgreSQL 16. Loaded into podman on the server.
Service unitssystemd/Quadlet files so the three containers start at boot, restart on failure, and report health to systemctl.
mailflow-ctlThe one management command: status, logs, backup, restore, upgrade, rollback, uninstall and more. Chapter 10.
Backup timersHourly pg_dump and a daily retention rotation, installed and enabled for you.
podman RPMsSo a server that has never had podman can still install. Skipped entirely when podman is present.
ComponentsVoice models for server-side speech search, and a demo warehouse. Ticked or unticked during install, chapter 13.

The version string, for example 0.1.0-20260906.1125.f644a68b, reads as app version, build date and time, and the git commit it was built from. A trailing .dirty means uncommitted changes were included, which is normal for a development build.

03Before you begin

A short readiness check before setup: a supported server, enough space, an available web address, and an administrator with a phone.

The server

RequirementMinimumRecommended
Operating systemOracle Linux 9. Other RHEL 9 family systems (Rocky, Alma, RHEL) work too. x86_64 only: the images are built for it.
CPU2 vCPU4–8 vCPU
Memory4 GB8–16 GB. Add 1.6 GB while the Large voice model is loaded.
Disk50 GB SSD100–200 GB SSD. Images take ~5 GB; backups and uploads grow with use.
Free space at install time~10 GB: about 5 GB scratch under /var/tmp (removed afterwards) plus the image store under /var/lib/containers.
systemdRunning. It is on every OL9 install.
podman4.4 or newer. If absent, the installer installs it from its own bundle.
Rootsudo for the install and for mailflow-ctl afterwards.
SELinux / firewalldBoth may stay on. The installer opens the web port in firewalld itself.

The network

Only the web port comes in. Everything else is the server reaching out to systems you already have.

DirectionPortPurpose
Inbound80/tcp configurableThe web UI. Put a TLS proxy in front for HTTPS.
Outbound25 · 587 · 465Your SMTP relays, added later in Control Panel → SMTP.
Outbound1521 · 5432 · 3306 · 8080 · 1025The report-source databases you connect (Oracle, Postgres, MySQL, Trino, Teradata).
Outbound389 · 636Active Directory, if LDAP login is used.
Outbound993 · 22IMAP bounce mailboxes and SSH jump hosts, if configured.
HTTPS

The installer serves plain HTTP. Terminate TLS on your load balancer or on an nginx/haproxy in front, pointing at the port you chose. To keep the UI reachable only through that proxy, install with --bind 127.0.0.1 (chapter 14).

The people

Before you start

  • An email address for the first (break-glass) admin.
  • That person's phone with Microsoft Authenticator, Google Authenticator, Authy or FreeOTP.
  • Your SMTP relay's host, port, TLS mode and credentials, for the first send.

Good to have

  • A safe, off-server place for one small secrets file (chapter 9).
  • The host, port and a read-only login of one report database, to try a first query.
  • Your AD base DN and a service account, if LDAP login is planned.
Part II · Set up MailFlow

04Copy MailFlow to the server

Move the installation file and its verification file to the server, then confirm the copy arrived intact.

Use whatever crosses the air gap: scp, a USB drive, a file share. Then confirm the copy is intact.

from your workstation
$ scp mailflow-0.1.0-20260906.1125.f644a68b.run* admin@server:/var/tmp/
$ ssh admin@server
$ cd /var/tmp && sha256sum -c mailflow-0.1.0-20260906.1125.f644a68b.run.sha256
mailflow-0.1.0-20260906.1125.f644a68b.run: OK

The installer verifies its own payload again when it runs, so a truncated copy fails safely instead of installing half a system. Three questions it can answer without unpacking anything:

instant, no root needed
$ bash mailflow-0.1.0-20260906.1125.f644a68b.run --version
$ bash mailflow-0.1.0-20260906.1125.f644a68b.run --list-components
$ bash mailflow-0.1.0-20260906.1125.f644a68b.run --help

05Set up MailFlow

Run a safety check first, then start the installation. MailFlow guides you through the few choices it needs.

Step 1 · Preflight only

This changes nothing. It checks the OS, architecture, systemd, podman, disk space, whether the port is free, SELinux and firewalld, and whether MailFlow is already installed.

on the server
$ sudo bash mailflow-0.1.0-20260906.1125.f644a68b.run --check
what you should see
==> MailFlow 0.1.0-20260906.1125.f644a68b installer -- preflight
  ✓ running as root
  ✓ operating system                   Oracle Linux Server 9.4
  ✓ architecture                       x86_64
  ✓ systemd                            running
  ✓ podman                             5.4.0
  ✓ tar · gzip · curl
  ✓ python3 (backup rotation)          3.9.21
  ✓ image archive                      2.7G
  ✓ disk space for images              180 GiB free on /var/lib/containers
  ✓ existing install                   none -- fresh install into /etc/mailflow
  ✓ port 80 free
  ✓ SELinux                            Enforcing
  ✓ firewalld                          running -- port 80/tcp will be opened
  ✓ optional components                3 available
 ok  preflight passed; nothing was changed (--check).

A red ✗ line explains what to fix. Nothing is installed until every check passes. A ! line is a warning you may accept.

Step 2 · Install

Press Play to watch the whole interactive run as it appears on the server, including the three questions it asks.

root@ol9-server:/var/tmp
Press Play to run the install.
  1. Optional components

    A checklist. Type a number to tick or untick a line, a for all, n for none, then Enter. Chapter 13 explains each one; the picker below totals the footprint.

  2. Proceed?

    A summary of where files go, which services are created, and the URL. Answer y.

  3. Create the break-glass admin now?

    Answer y, then a username, an email, and a password (12 characters minimum, typed twice, never echoed). This is the account you log in with first. It can also be done later with sudo mailflow-ctl create-admin.

Choose components

Tick what the server should carry. The summary updates, and the last line is the exact non-interactive flag for this selection.

6.6 GBinstalled footprint (images 5.0 GB + components)
1.6 GBextra RAM while a voice model is loaded
large-v3-turboactive voice model after install
sudo bash mailflow-<version>.run --components whisper-large-v3-turbo

Non-interactive install

For scripted or unattended runs, pass everything on the command line. -y answers every question.

unattended
$ sudo bash mailflow-0.1.0-20260906.1125.f644a68b.run -y \
    --port 8080 --tz Asia/Dhaka \
    --components whisper-large-v3-turbo,demo-data \
    --admin-user admin --admin-email admin@example.com --admin-password 'a-long-passphrase-here'

A second copy on the same server

An instance is a fully independent MailFlow with its own database, port and services, living beside the default one. Useful as a staging copy before upgrading production.

staging beside production
$ sudo bash mailflow-0.1.0-20260906.1125.f644a68b.run --instance staging --port 8081

Its command is mailflow-staging-ctl; its files live under /etc/mailflow-staging, /opt/mailflow-staging and /var/lib/mailflow-staging; its services are mailflow-staging-*.

06Setup choices

ADMIN REFERENCE

Most installations can use the defaults. This section lists the available choices when your environment needs something different.

OptionEffect
--versionPrint the bundled MailFlow version.
--list-componentsList the optional components with ids and sizes.
--helpAll options, including the ones below.
--extract-only=DIRUnpack the payload into DIR and stop, for inspection.
--tmpdir=DIRUnpack somewhere other than /var/tmp. Needs ~5 GB free.
--no-verifySkip the payload checksum. Saves a minute on slow disks; only after sha256sum -c passed.
OptionEffect
--checkPreflight only. Changes nothing.
-y, --yesNo questions. Components fall back to their defaults unless --components is given; no admin unless --admin-* are given.
--port NHost port for the web UI. Default 80 (8080 with --user).
--bind ADDRListen on one address only, e.g. 127.0.0.1 behind a local TLS proxy. Default: all addresses.
--tz ZONETimezone schedules are read in. Default Asia/Dhaka.
--instance NAMEInstall a named, independent stack beside the default one.
--components LISTComma-separated ids, or all, none, default.
--no-firewallLeave firewalld alone.
--no-startInstall but do not start the services.
--no-backup-timersDo not enable the hourly backup and daily rotation timers.
--userRootless install for the current Linux user under systemctl --user. For testing on a workstation, not for servers.
OptionEffect
--admin-user U --admin-email ECreate the break-glass admin without the question. The password is prompted, not echoed.
--admin-password PGive the password on the command line for fully unattended runs. It lands in your shell history: prefer a space before the command or clear it afterwards.
--skip-adminCreate no admin now. Do it later with sudo mailflow-ctl create-admin --username U --email E.

07What MailFlow sets up for you

ADMIN REFERENCE

A plain-language view of what the installer prepares automatically. You can skip this section unless you administer the server.

  1. Preflight

    The checks from chapter 5. Any failure stops here with nothing changed.

  2. Plan and confirmation

    Component checklist, then the summary and the Proceed question.

  3. podman, only if missing

    Installs the bundled RPMs that are not already present. Never downgrades anything that is.

  4. Pre-upgrade dump

    On an existing install only: a pg_dump into the backups directory before anything else changes.

  5. Images

    podman load of the three images, tagged with this version and as latest. The slowest step, a few minutes.

  6. Program files

    mailflow-ctl, the uninstaller, backup scripts and notes into /opt/mailflow; the command linked into /usr/local/bin.

  7. Secrets

    On a fresh install: a database password, the encryption key (Fernet) and the session-token secret, generated locally into /etc/mailflow/*.env with mode 600. On an upgrade these files are not touched.

  8. Service units

    Quadlet files for the three containers, the network and two volumes; backup timers; systemctl daemon-reload; timers enabled.

  9. Firewall

    Opens the web port in firewalld if it is running.

  10. Voice models

    Copies the ticked Whisper models into the data volume, before the app starts, so the configuration never names a model that is not there.

  11. Start

    Database, then backend (which applies schema migrations on boot), then web. Waits until /healthz answers through nginx, up to four minutes.

  12. Demo data

    If ticked: builds the mailflow_demo warehouse and seeds the sample connection, queries, variables and emails, all with schedules off.

  13. Admin and summary

    Creates the break-glass account if asked, prints the URL and the commands you will use from now on, deletes its scratch directory.

What is running afterwards

Oracle Linux 9 host systemd · podman (rootful) · firewalld · SELinux podman network "mailflow" mailflow-frontendnginx · built UIproxies /api → backend:8080 inside mailflow-backendFastAPI · schedulerrenderer · SMTP sender:8000 · host metrics mailflow-pg-podPostgreSQL 16app state only:5432 Browserhttp://server:80(or your TLS proxy) volume mailflow-datauploads · photos · voice models volume mailflow-postgres-datathe database files systemd timersbackup (hourly) · backup-rotate (daily) /etc/mailflow/ backend.env postgres.env install.conf /var/lib/mailflow/ backups/*.dump
Part III · First use

08Your first sign-in

Open MailFlow, sign in with the administrator account, and connect your authenticator app for secure access.

Codes and clocks

The code changes every 30 seconds; the current and the adjacent one are accepted, so a phone whose clock is a minute off is rejected. Five wrong codes within 15 minutes lock the account for 15 minutes.

Locked out of the phone?

Can't access authenticator? emails a one-time code, but only once an SMTP relay is configured (chapter 9). Until then, the break-glass admin's phone is the only second factor. Enrol it carefully and keep the manual key somewhere safe.

Creating the other users

There is no sign-up page. In Control Panel → Users & Access an admin creates each account with a username, display name, email, role, and an authentication source: local (a password set by the admin, which the user can reset by email once SMTP exists) or LDAP (the user's Active Directory password). Every user enrols an authenticator on their first login. An admin can reset a user's authenticator from the same page; an AD group can be mapped to a role so membership sets the role automatically.

RoleCanTypical person
viewerSee emails, delivery reports and previews.A manager who receives the reports and wants to check what went out.
composerAlso create and edit queries, emails, variables and the address book; run dry-runs; trigger sends.The analyst who writes the reports.
adminAlso manage database connections, users and roles, SMTP and SFTP settings, housekeeping, the System Monitor and the audit log.The owner of the system.

09First-day checklist

A short checklist to confirm MailFlow is protected, reachable, and ready for scheduled reporting.

Part IV · Run and protect

10Everyday operations

The few commands an administrator normally needs to check MailFlow, restart it, or review activity.

ServiceContainerRole
mailflow-postgres.servicemailflow-pg-podThe app database (PostgreSQL 16). Data in volume mailflow-postgres-data.
mailflow-backend.servicemailflow-backendAPI, scheduler, rendering, sending. Uploads, photos and voice models in volume mailflow-data.
mailflow-frontend.servicemailflow-frontendnginx: serves the UI, proxies /api to the backend, owns the published port.
mailflow-backup.timer—Hourly pg_dump.
mailflow-backup-rotate.timer—Daily retention rotation. Dry-run until enabled.
the management command
$ sudo mailflow-ctl status          # services, container health, /healthz, newest backup
$ sudo mailflow-ctl stop            # web → backend → database
$ sudo mailflow-ctl start           # database → backend → web, then waits for healthy
$ sudo mailflow-ctl restart
$ sudo mailflow-ctl logs backend    # last 200 lines; also: pg, frontend
$ sudo mailflow-ctl logs backend -f # follow live
$ sudo mailflow-ctl health          # {"status":"ok","db":"ok","backup_age_seconds":1832.4}
$ sudo mailflow-ctl shell           # a shell inside the backend container
$ sudo mailflow-ctl psql            # psql on the app database
$ sudo mailflow-ctl paths           # every directory, unit, container and volume name
$ sudo mailflow-ctl help
one service at a time
$ sudo systemctl status mailflow-backend.service
$ sudo systemctl restart mailflow-backend.service     # the app only; the UI keeps serving
$ sudo systemctl restart mailflow-frontend.service    # nginx only
$ sudo systemctl restart mailflow-postgres.service    # restarts the backend with it
$ sudo journalctl -u mailflow-backend.service -n 200 --no-pager
$ sudo journalctl -u mailflow-backend.service -f
$ sudo systemctl list-timers 'mailflow-*'

All three start at boot and restart on their own after a crash. Stopping one with systemctl stop keeps it stopped until the next boot or a start.

container level
$ sudo podman ps                                    # the three containers and their health
$ sudo podman logs --tail 100 mailflow-backend
$ sudo podman exec -it mailflow-backend bash
$ sudo podman exec mailflow-pg-pod pg_isready -U mailflow
$ sudo podman volume inspect mailflow-data          # where uploads live on disk
$ sudo podman images | grep mailflow

Prefer systemctl for starting and stopping: a container stopped with podman stop is restarted by systemd within seconds.

sudo mailflow-ctl status
MailFlow 0.1.0-20260906.1125.f644a68b -- system mode

  SERVICE                      STATE      CONTAINER
  mailflow-postgres            active     running / healthy
  mailflow-backend             active     running / healthy
  mailflow-frontend            active     running
  mailflow-backup.timer        active     next: Mon 2026-09-07 12:00:23 +06
  mailflow-backup-rotate.timer active     next: Tue 2026-09-08 00:04:56 +06

  health   OK  http://127.0.0.1:80/healthz
           {"status":"ok","db":"ok","backup_age_seconds":1832.4}
  backups  26 dumps, newest mailflow_20260907_110023.dump (2.1M)
  rotation dry-run (logs only; 'mailflow-ctl rotation enable' to go live)
When to restart

Restarting the backend is safe, but a send that was in flight at that moment is not retried on its own: check the email's Report page afterwards and use Resend if needed. Prefer a quiet minute between scheduled sends.

11Protect and restore your data

MailFlow creates regular database backups automatically. Keep one important key file safe as well, so recovery stays straightforward.

What is backed up automatically

Every hour a pg_dump of the app database lands in /var/lib/mailflow/backups/mailflow_YYYYMMDD_HHMMSS.dump. It is PostgreSQL's compressed custom format and holds everything MailFlow knows: users, connections, queries, emails, schedules, the delivery ledger, settings. /healthz reports the age of the newest dump so a monitor can alarm on a stale one.

In the dump

  • Users, roles, authenticator secrets (encrypted)
  • Connections, queries, variables, emails, versions
  • Schedules, SMTP/SFTP profiles (encrypted)
  • The delivery ledger and audit log

Not in the dump

  • The encryption key: /etc/mailflow/backend.env
  • Uploaded pictures, people photos, voice models: volume mailflow-data
  • Rendered attachments (regenerated on every send)

Cover the first two with your normal file backup.

on demand
$ sudo mailflow-ctl backup
mailflow-backup: wrote /var/lib/mailflow/backups/mailflow_20260907_113512.dump (2201344 bytes)
$ ls -lh /var/lib/mailflow/backups/ | tail -5

Retention

Rotation keeps the last 24 hourly, 7 daily, 4 weekly and 12 monthly dumps: 47 files. It ships in dry-run and only logs which files it would delete. After you have read one run's output, switch it on.

rotation
$ sudo journalctl -u mailflow-backup-rotate --no-pager | tail     # read the WOULD DELETE lines
$ sudo mailflow-ctl rotation enable                                # also: disable | status

Restoring a dump

Read first

The dump must have been taken under the same encryption key that is in /etc/mailflow/backend.env now. A dump from a server whose key was different restores fine but leaves every stored password and authenticator secret unreadable. When rebuilding a server, restore the key file first.

restore
$ sudo mailflow-ctl restore /var/lib/mailflow/backups/mailflow_20260907_110023.dump

It asks for confirmation, takes a safety dump of the current database, stops the backend, drops and recreates the database, restores, starts the backend (which applies any pending migrations) and waits for healthy. Users are signed out.

Rebuilding a server from scratch

  1. Install MailFlow on the new server

    With the installer, --skip-admin. Choose the same components.

  2. Put the old key back

    Copy the saved backend.env over /etc/mailflow/backend.env, keeping only the new server's MAILFLOW_DATABASE_URL line. Then sudo mailflow-ctl restart.

  3. Restore the dump

    sudo mailflow-ctl restore /path/to/mailflow_….dump. Your users, their authenticators, connections and relays are back.

  4. Copy the data volume back

    If you have it: sudo podman volume inspect mailflow-data shows the directory to copy into. Restart afterwards.

12Update MailFlow safely

Use the newer installation file. MailFlow protects the current data first and keeps a simple way back if needed.

The installer notices the existing installation and switches to upgrade mode: secrets, database, uploads and port are kept, and a pre-upgrade dump is written before anything changes.

upgrade
$ sudo bash mailflow-0.1.0-20260920.0930.a1b2c3d4.run --check    # shows: this is an UPGRADE
$ sudo bash mailflow-0.1.0-20260920.0930.a1b2c3d4.run
what an upgrade prints
==> Plan: UPGRADE mailflow 0.1.0-20260906.1125.f644a68b -> 0.1.0-20260920.0930.a1b2c3d4
  · a pre-upgrade database dump goes to /var/lib/mailflow/backups
  · secrets, database, uploaded files and port 80 are kept
  · services restart; pending schema migrations run at backend start
Proceed? [y/N] y
==> Taking a pre-upgrade database dump
mailflow-backup: wrote /var/lib/mailflow/backups/mailflow_20260920_100412.dump (2214410 bytes)
==> Loading container images (this takes a few minutes)
 ok  images loaded: mailflow-backend:0.1.0-20260920.0930.a1b2c3d4, mailflow-frontend:…, postgres:16
==> Restarting services on the new version
==> Waiting for the app to answer at http://127.0.0.1:80/healthz
...
 ok  healthy

Users are signed out for the restart; plan it between scheduled sends. On an upgrade the component checklist appears again: leave everything unticked to change nothing, tick a model to add it.

Rolling back

rollback
$ sudo mailflow-ctl rollback

Points the services back at the previous version's images and restarts. Database schema changes made by the newer version are not undone; if the old version cannot run on the new schema, restore the pre-upgrade dump instead (chapter 11). The previous version's images are kept for exactly this; sudo mailflow-ctl prune removes anything older.

A safe upgrade routine

Install the new file as --instance staging --port 8081, restore last night's production dump into it, click around, then upgrade production. Remove staging afterwards with sudo mailflow-staging-ctl uninstall --purge.

13Optional features

ADMIN REFERENCE

Add only the extras your environment needs. They can be included during setup or changed later.

Voice models

The global search box has a microphone. Two engines work in the browser with no help from the server. The third, server-side transcription, needs a Whisper model on the server and is the most accurate. The installer offers the models as components; the largest ticked one becomes active.

ComponentOn diskRAM while loadedNotes
whisper-large-v3-turbo default1.6 GB~1.6 GBNear-Large accuracy, several times faster than Large.
whisper-tiny75 MB~0.2 GBFor small servers. Noticeably lower accuracy.

The model loads lazily on the first voice request and can be unloaded from System Monitor → Runtime. Switch models later without reinstalling:

voice model
$ sudo mailflow-ctl whisper           # active model + what is installed
$ sudo mailflow-ctl whisper tiny      # switch, restarts the backend

Demo data

demo-data builds a separate mailflow_demo database (payments-style data, about 173,000 rows) inside the same PostgreSQL, adds a read-only connection to it, 38 queries each with a chart or table preset, 5 variables and 9 sample emails. Every sample schedule is disabled. It is the fastest way to train people on the Composer before real connections exist.

removing the demo later
# 1. delete the [Demo] emails, queries, variables and connection in the UI, then:
$ sudo mailflow-ctl psql -d postgres -c "DROP DATABASE mailflow_demo"

14Change server settings

ADMIN REFERENCE

Most day-to-day settings belong in MailFlow itself. Only a small number of server settings need administrator access.

Web port or bind address

port / bind
$ sudo nano /etc/mailflow/install.conf       # MAILFLOW_PORT="8443"   MAILFLOW_BIND="127.0.0.1"
$ sudo mailflow-ctl reconfigure && sudo mailflow-ctl restart
$ sudo firewall-cmd --permanent --add-port=8443/tcp && sudo firewall-cmd --reload

Timezone

Schedules ("every weekday at 08:00") are read in this zone. Change MAILFLOW_TZ in backend.env, then sudo mailflow-ctl restart. Settings → Scheduler shows the zone the app is actually using.

The environment file

/etc/mailflow/backend.envMeaningChange it?
MAILFLOW_DATABASE_URLConnection to the app database. The host is the database container's name.only if you move the database
MAILFLOW_SECRET_KEYEncrypts every stored password and authenticator secret.never keep a copy off-box
MAILFLOW_JWT_SECRETSigns login sessions. Changing it signs everyone out.only to force a global sign-out
MAILFLOW_TZSchedule timezone.yes
MAILFLOW_WHISPER_MODELActive voice model.via mailflow-ctl whisper
MAILFLOW_DATA_DIR · MAILFLOW_BACKUP_DIRPaths inside the container.no
MAILFLOW_PROC_ROOT · MAILFLOW_CGROUP_ROOTLet System Monitor read the host's CPU and memory, not the container's.no

/etc/mailflow/postgres.env holds the database user, password and name. Leave it alone; the URL above embeds the same password.

15Files and storage

ADMIN REFERENCE

A reference for administrators who need to know where MailFlow keeps configuration, backups, and application data.

system install, default instance
/etc/mailflow/
  install.conf                instance, version, port, bind, paths — edit port/bind here
  backend.env                 app secrets and settings                         mode 600
  postgres.env                database credentials                             mode 600
/opt/mailflow/
  VERSION
  README-INSTALL.md           the short version of this handbook
  bin/mailflow-ctl            linked as /usr/local/bin/mailflow-ctl
  bin/uninstall.sh
  scripts/backup_db.sh        what the hourly timer runs
  scripts/rotate_backups.py   what the daily timer runs
  components/demo-data/       demo seed scripts, if installed
/var/lib/mailflow/backups/    mailflow_YYYYMMDD_HHMMSS.dump …
/etc/containers/systemd/      mailflow-postgres.container  mailflow-backend.container  mailflow-frontend.container
                              mailflow.network  mailflow-data.volume  mailflow-postgres-data.volume
/etc/systemd/system/          mailflow-backup.{service,timer}  mailflow-backup-rotate.{service,timer}
podman volumes                mailflow-postgres-data (database)   mailflow-data (uploads, photos, voice models)
podman images                 localhost/mailflow-backend:<version>  localhost/mailflow-frontend:<version>  postgres:16

sudo mailflow-ctl paths prints the same list with the real names. For a named instance everything becomes mailflow-<name>…; for a rootless install the same layout sits under ~/.config and ~/.local/share.

16Remove MailFlow

ADMIN REFERENCE

Choose whether to remove only the application or also erase its stored data and backups.

uninstall
$ sudo mailflow-ctl uninstall             # services, units, program files, images
$ sudo mailflow-ctl uninstall --purge     # also the database, uploads, secrets and backups

Without --purge the database volume, the data volume, /etc/mailflow/*.env and the backups stay on disk, and running the installer again adopts them: same data, same key, nothing lost. --purge asks you to type DELETE.

17Solve common problems

ADMIN REFERENCE

Find the symptom, see the likely cause, and follow the suggested fix.

Preflight: "port 80 free" fails

Something else listens there, often the OS's own httpd or an old app. Install with --port 8080, or stop that service first: sudo ss -ltnp 'sport = :80' names it.

Preflight: podman not installed and no RPM bundle

This installer was built without the podman RPMs. Install podman from the OS media (dnf install podman against the local repo or DVD) and run the installer again.

Preflight: not enough disk space

About 5 GB is needed under /var/lib/containers for the images. The scratch copy under /var/tmp can go elsewhere with --tmpdir=/data/tmp.

"verifying payload checksum... FAILED"

The file is truncated or corrupt. Copy it again and check it against the .sha256 file with sha256sum -c before running.

"the app did not become healthy in time"

Run sudo mailflow-ctl logs backend. A wrong or unreachable database shows there, and so does a migration error. Fix the cause, then sudo mailflow-ctl start. The install itself is complete at that point; nothing needs re-running.

The UI loads but every action fails

The backend is down or restarting: sudo mailflow-ctl status. nginx keeps serving the UI while the backend is away, so the page itself is not a health signal. sudo mailflow-ctl health is.

Can't reach the UI from another machine

Firewall. sudo firewall-cmd --list-ports should list your port. A cloud or hardware firewall in front of the server needs the same port opened. From the server itself, curl -s http://127.0.0.1/healthz proves the app is fine.

Login says "access not authorized"

The account does not exist or is disabled. Only accounts created by an admin can sign in, even with a correct Active Directory password. Check Control Panel → Users & Access.

Authenticator codes are rejected

Phone clock drift: enable automatic time on the phone. Five failures within 15 minutes lock the account for 15 minutes. An admin can reset the authenticator from Users & Access; the user enrols again on the next login.

The break-glass admin lost their phone and no SMTP is set up

Create a second admin from the server: sudo mailflow-ctl create-admin --username admin2 --email …, sign in with it, enrol a phone, then reset the first admin's authenticator from Users & Access.

Emails do not send on schedule

In order of likelihood: the Settings → Scheduler master switch is off (it ships off); the email's state is Paused or Draft; no SMTP profile is Active; the relay refused the sender. The email's Report page shows every run with the failure reason and the relay's exact reply per recipient.

System Monitor shows the container's numbers, not the host's

On an SELinux-enforcing host the /proc and /sys/fs/cgroup bind mounts may be denied: sudo ausearch -m avc -ts recent shows it. The app itself is unaffected; only that page is.

Voice search says the server model is not available

No model was ticked at install. sudo mailflow-ctl whisper lists what is present. Re-run the same installer file with a model ticked; it upgrades in place and adds the model.

Backup age keeps growing

systemctl status mailflow-backup.timer and journalctl -u mailflow-backup. Usually a full disk, sometimes a stopped database container.

Restore says the database is not ready

The database container must be running for a restore: sudo systemctl start mailflow-postgres.service, then retry.

For anything else: sudo mailflow-ctl status, then the logs of whichever line is not active / healthy.

Part V · Administrator reference

18Build the installation package

ADMIN REFERENCE

Developer-only reference for producing the offline installation file. Day-to-day users and server operators can skip this section.

deploy/installer/build-installer.sh builds both container images from the current tree, pulls PostgreSQL if needed, resolves the podman RPMs inside a minimal Oracle Linux 9 container, fetches any missing Whisper models, and writes dist/mailflow-<version>.run. It needs internet access once for those fetches; the produced file never does.

build
$ deploy/installer/build-installer.sh                  # full build, about 15 minutes
$ deploy/installer/build-installer.sh --no-build       # reuse the images already built
$ deploy/installer/build-installer.sh --whisper tiny --no-demo --no-rpms
$ ls -lh dist/                                         # mailflow-latest.run → newest build
deploy/installer/build.confDefaultMeaning
WHISPER_MODELSlarge-v3-turbo,tinyModels to bundle as components; the first is ticked by default. Also available: large-v3, medium, small, base.
DEMO1Bundle the demo-data component.
RPMS1Bundle podman's RPMs.
GZIP_LEVEL61 is several minutes faster and about 10% bigger.
KEEP2How many builds to keep in dist/.
WATCH_INTERVAL · WATCH_QUIET120 · 600 sHow often the watcher looks, and how long the tree must stay unchanged before it rebuilds.

Keeping it current automatically

The watcher fingerprints the source tree (backend app, migrations, vendored drivers, frontend sources, docs, the installer itself) and rebuilds once the tree has changed and then stayed quiet for ten minutes, so a burst of edits yields one build. It runs as a user-level systemd service.

watcher
$ deploy/installer/watch-rebuild.sh --install-service    # once
$ deploy/installer/watch-rebuild.sh --status
$ deploy/installer/watch-rebuild.sh --once               # rebuild now if anything changed
$ deploy/installer/watch-rebuild.sh --force              # rebuild regardless
$ tail -f dist/build.log

To keep the service running after logout, an administrator runs loginctl enable-linger <user> once.

Testing an installer without a server

A rootless install on the development machine runs the whole installer, including the upgrade path, under your own user with no sudo, beside the development database:

rootless test instance
$ bash dist/mailflow-latest.run --user --instance test --port 8081
$ mailflow-test-ctl status
$ mailflow-test-ctl uninstall --purge

19Administrator quick reference

ADMIN REFERENCE

The essential maintenance commands in one place for experienced administrators.

mailflow — quick reference
# install / upgrade
sudo bash mailflow-<version>.run --check
sudo bash mailflow-<version>.run
sudo bash mailflow-<version>.run -y --components whisper-tiny --admin-user admin --admin-email a@b.c

# run
sudo mailflow-ctl status | start | stop | restart | health
sudo mailflow-ctl logs backend -f                # pg | backend | frontend
sudo mailflow-ctl create-admin --username U --email E

# protect
sudo cp /etc/mailflow/backend.env /secure/offbox/   # the encryption key — once
sudo mailflow-ctl backup
sudo mailflow-ctl rotation enable
sudo mailflow-ctl restore /var/lib/mailflow/backups/mailflow_YYYYMMDD_HHMMSS.dump

# change
sudo mailflow-ctl whisper tiny
sudo nano /etc/mailflow/install.conf && sudo mailflow-ctl reconfigure && sudo mailflow-ctl restart
sudo mailflow-ctl rollback
sudo mailflow-ctl uninstall [--purge]
↑ Top