Connect your data
Use the databases and spreadsheet-based sources your reports already depend on.
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.
MailFlow turns the reports you repeatedly prepare and send into a dependable, scheduled workflow.
Use the databases and spreadsheet-based sources your reports already depend on.
Combine written context with live tables, charts, and the attachments your recipients need.
MailFlow prepares and sends each report automatically, then keeps a record of the delivery.
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.
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.
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.
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.
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.
Everything needed for an offline installation is carried in one installation file. Nothing needs to be downloaded on the server.
| Piece | What it is for |
|---|---|
| Container images | MailFlow 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 units | systemd/Quadlet files so the three containers start at boot, restart on failure, and report health to systemctl. |
mailflow-ctl | The one management command: status, logs, backup, restore, upgrade, rollback, uninstall and more. Chapter 10. |
| Backup timers | Hourly pg_dump and a daily retention rotation, installed and enabled for you. |
| podman RPMs | So a server that has never had podman can still install. Skipped entirely when podman is present. |
| Components | Voice 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.
A short readiness check before setup: a supported server, enough space, an available web address, and an administrator with a phone.
| Requirement | Minimum | Recommended |
|---|---|---|
| Operating system | Oracle Linux 9. Other RHEL 9 family systems (Rocky, Alma, RHEL) work too. x86_64 only: the images are built for it. | |
| CPU | 2 vCPU | 4–8 vCPU |
| Memory | 4 GB | 8–16 GB. Add 1.6 GB while the Large voice model is loaded. |
| Disk | 50 GB SSD | 100–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. | |
| systemd | Running. It is on every OL9 install. | |
| podman | 4.4 or newer. If absent, the installer installs it from its own bundle. | |
| Root | sudo for the install and for mailflow-ctl afterwards. | |
| SELinux / firewalld | Both may stay on. The installer opens the web port in firewalld itself. | |
Only the web port comes in. Everything else is the server reaching out to systems you already have.
| Direction | Port | Purpose |
|---|---|---|
| Inbound | 80/tcp configurable | The web UI. Put a TLS proxy in front for HTTPS. |
| Outbound | 25 · 587 · 465 | Your SMTP relays, added later in Control Panel → SMTP. |
| Outbound | 1521 · 5432 · 3306 · 8080 · 1025 | The report-source databases you connect (Oracle, Postgres, MySQL, Trino, Teradata). |
| Outbound | 389 · 636 | Active Directory, if LDAP login is used. |
| Outbound | 993 · 22 | IMAP bounce mailboxes and SSH jump hosts, if configured. |
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).
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.
$ 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:
$ 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
Run a safety check first, then start the installation. MailFlow guides you through the few choices it needs.
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.
$ sudo bash mailflow-0.1.0-20260906.1125.f644a68b.run --check==> 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.
Press Play to watch the whole interactive run as it appears on the server, including the three questions it asks.
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.
A summary of where files go, which services are created, and the URL. Answer y.
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.
Tick what the server should carry. The summary updates, and the last line is the exact non-interactive flag for this selection.
For scripted or unattended runs, pass everything on the command line. -y answers every question.
$ 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'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.
$ sudo bash mailflow-0.1.0-20260906.1125.f644a68b.run --instance staging --port 8081Its 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-*.
Most installations can use the defaults. This section lists the available choices when your environment needs something different.
| Option | Effect |
|---|---|
--version | Print the bundled MailFlow version. |
--list-components | List the optional components with ids and sizes. |
--help | All options, including the ones below. |
--extract-only=DIR | Unpack the payload into DIR and stop, for inspection. |
--tmpdir=DIR | Unpack somewhere other than /var/tmp. Needs ~5 GB free. |
--no-verify | Skip the payload checksum. Saves a minute on slow disks; only after sha256sum -c passed. |
| Option | Effect |
|---|---|
--check | Preflight only. Changes nothing. |
-y, --yes | No questions. Components fall back to their defaults unless --components is given; no admin unless --admin-* are given. |
--port N | Host port for the web UI. Default 80 (8080 with --user). |
--bind ADDR | Listen on one address only, e.g. 127.0.0.1 behind a local TLS proxy. Default: all addresses. |
--tz ZONE | Timezone schedules are read in. Default Asia/Dhaka. |
--instance NAME | Install a named, independent stack beside the default one. |
--components LIST | Comma-separated ids, or all, none, default. |
--no-firewall | Leave firewalld alone. |
--no-start | Install but do not start the services. |
--no-backup-timers | Do not enable the hourly backup and daily rotation timers. |
--user | Rootless install for the current Linux user under systemctl --user. For testing on a workstation, not for servers. |
| Option | Effect |
|---|---|
--admin-user U --admin-email E | Create the break-glass admin without the question. The password is prompted, not echoed. |
--admin-password P | Give 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-admin | Create no admin now. Do it later with sudo mailflow-ctl create-admin --username U --email E. |
A plain-language view of what the installer prepares automatically. You can skip this section unless you administer the server.
The checks from chapter 5. Any failure stops here with nothing changed.
Component checklist, then the summary and the Proceed question.
Installs the bundled RPMs that are not already present. Never downgrades anything that is.
On an existing install only: a pg_dump into the backups directory before anything else changes.
podman load of the three images, tagged with this version and as latest. The slowest step, a few minutes.
mailflow-ctl, the uninstaller, backup scripts and notes into /opt/mailflow; the command linked into /usr/local/bin.
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.
Quadlet files for the three containers, the network and two volumes; backup timers; systemctl daemon-reload; timers enabled.
Opens the web port in firewalld if it is running.
Copies the ticked Whisper models into the data volume, before the app starts, so the configuration never names a model that is not there.
Database, then backend (which applies schema migrations on boot), then web. Waits until /healthz answers through nginx, up to four minutes.
If ticked: builds the mailflow_demo warehouse and seeds the sample connection, queries, variables and emails, all with schedules off.
Creates the break-glass account if asked, prints the URL and the commands you will use from now on, deletes its scratch directory.
Open MailFlow, sign in with the administrator account, and connect your authenticator app for secure access.
The one printed at the end of the install, for example http://10.20.30.40/. Behind a TLS proxy, use the proxy's address.
Username and password you gave the installer. Leave Trust this device for 12 hours ticked unless the machine is shared.
The account has no second factor yet, so MailFlow shows a QR code. Scan it with Microsoft Authenticator, Google Authenticator, Authy or FreeOTP (or type the manual key), then enter the six-digit code it shows.
Sessions last 8 hours and refresh while you work. On a trusted device the next sign-in within 12 hours skips the code.
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.
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.
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.
| Role | Can | Typical person |
|---|---|---|
| viewer | See emails, delivery reports and previews. | A manager who receives the reports and wants to check what went out. |
| composer | Also create and edit queries, emails, variables and the address book; run dry-runs; trigger sends. | The analyst who writes the reports. |
| admin | Also manage database connections, users and roles, SMTP and SFTP settings, housekeeping, the System Monitor and the audit log. | The owner of the system. |
A short checklist to confirm MailFlow is protected, reachable, and ready for scheduled reporting.
The few commands an administrator normally needs to check MailFlow, restart it, or review activity.
| Service | Container | Role |
|---|---|---|
mailflow-postgres.service | mailflow-pg-pod | The app database (PostgreSQL 16). Data in volume mailflow-postgres-data. |
mailflow-backend.service | mailflow-backend | API, scheduler, rendering, sending. Uploads, photos and voice models in volume mailflow-data. |
mailflow-frontend.service | mailflow-frontend | nginx: 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. |
$ 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
$ 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.
$ 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.
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)
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.
MailFlow creates regular database backups automatically. Keep one important key file safe as well, so recovery stays straightforward.
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.
/etc/mailflow/backend.envmailflow-dataCover the first two with your normal file backup.
$ 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
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.
$ sudo journalctl -u mailflow-backup-rotate --no-pager | tail # read the WOULD DELETE lines $ sudo mailflow-ctl rotation enable # also: disable | status
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.
$ sudo mailflow-ctl restore /var/lib/mailflow/backups/mailflow_20260907_110023.dumpIt 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.
With the installer, --skip-admin. Choose the same components.
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.
sudo mailflow-ctl restore /path/to/mailflow_….dump. Your users, their authenticators, connections and relays are back.
If you have it: sudo podman volume inspect mailflow-data shows the directory to copy into. Restart afterwards.
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.
$ 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
==> 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.
$ sudo mailflow-ctl rollbackPoints 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.
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.
Add only the extras your environment needs. They can be included during setup or changed later.
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.
| Component | On disk | RAM while loaded | Notes |
|---|---|---|---|
whisper-large-v3-turbo default | 1.6 GB | ~1.6 GB | Near-Large accuracy, several times faster than Large. |
whisper-tiny | 75 MB | ~0.2 GB | For 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:
$ sudo mailflow-ctl whisper # active model + what is installed $ sudo mailflow-ctl whisper tiny # switch, restarts the backend
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.
# 1. delete the [Demo] emails, queries, variables and connection in the UI, then: $ sudo mailflow-ctl psql -d postgres -c "DROP DATABASE mailflow_demo"
Most day-to-day settings belong in MailFlow itself. Only a small number of server settings need administrator access.
$ 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
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.
/etc/mailflow/backend.env | Meaning | Change it? |
|---|---|---|
MAILFLOW_DATABASE_URL | Connection to the app database. The host is the database container's name. | only if you move the database |
MAILFLOW_SECRET_KEY | Encrypts every stored password and authenticator secret. | never keep a copy off-box |
MAILFLOW_JWT_SECRET | Signs login sessions. Changing it signs everyone out. | only to force a global sign-out |
MAILFLOW_TZ | Schedule timezone. | yes |
MAILFLOW_WHISPER_MODEL | Active voice model. | via mailflow-ctl whisper |
MAILFLOW_DATA_DIR · MAILFLOW_BACKUP_DIR | Paths inside the container. | no |
MAILFLOW_PROC_ROOT · MAILFLOW_CGROUP_ROOT | Let 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.
A reference for administrators who need to know where MailFlow keeps configuration, backups, and application data.
/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.
Choose whether to remove only the application or also erase its stored data and backups.
$ 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.
Find the symptom, see the likely cause, and follow the suggested fix.
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.
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.
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.
The file is truncated or corrupt. Copy it again and check it against the .sha256 file with sha256sum -c before running.
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 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.
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.
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.
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.
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.
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.
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.
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.
systemctl status mailflow-backup.timer and journalctl -u mailflow-backup. Usually a full disk, sometimes a stopped database container.
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.
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.
$ 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.conf | Default | Meaning |
|---|---|---|
WHISPER_MODELS | large-v3-turbo,tiny | Models to bundle as components; the first is ticked by default. Also available: large-v3, medium, small, base. |
DEMO | 1 | Bundle the demo-data component. |
RPMS | 1 | Bundle podman's RPMs. |
GZIP_LEVEL | 6 | 1 is several minutes faster and about 10% bigger. |
KEEP | 2 | How many builds to keep in dist/. |
WATCH_INTERVAL · WATCH_QUIET | 120 · 600 s | How often the watcher looks, and how long the tree must stay unchanged before it rebuilds. |
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.
$ 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.
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:
$ bash dist/mailflow-latest.run --user --instance test --port 8081 $ mailflow-test-ctl status $ mailflow-test-ctl uninstall --purge
The essential maintenance commands in one place for experienced administrators.
# 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]