First install on Linux: the order of operations, Ubuntu to Enterprise Linux

Written for 6.3.4. hMailServer 6.3.8 (2 November 2026), a security release, is the release to install: as 6.3.7 (17 October 2026) did, beside the generic .deb and .rpm for x86-64 and AArch64 it carries a package for each of Debian 12 and 13, Ubuntu 24.04, Fedora 43 and 44, Enterprise Linux 9 and 10 and openSUSE Leap 16.0 and Tumbleweed, each installed in a clean container of its release by that release's own package manager before publication, so step 1 is apt, dnf or zypper with your release's own package; the AArch64 files are cross-compiled and tested under emulation. Check a download with sha256sum -c --ignore-missing hmailserver-linux-6.3.8-SHA256SUMS.txt first. See the 6.3.8 announcement.

The order matters more than the commands. The package installs the server enabled and stopped, on purpose: it has no database yet, and nothing in a package can know which backend you have or its credentials. The full sequence, with the output each step prints, is §35.3. Take the exact file names from the downloads page, and note the RPM carries a -1 release field in its name.

1. Install the package. sudo apt install ./<file>.deb on Ubuntu 26.04 or 24.04, sudo dnf install ./<file>.rpm on Fedora 43 or 44 or Enterprise Linux 10. 6.3.4's .deb needs glibc 2.38 or later, so it does not install on Debian 12; its .rpm does not install on Enterprise Linux 9, and nothing has been tried with zypper on openSUSE. The maintainer script creates the hmailserver system user and group, creates the directories, and enables the unit without starting it. It deliberately does not walk or chown an existing store.

2. If your backend is MySQL or MariaDB, install the client library now. The server opens it at run time and no package manager will pull it in: libmariadb3 on Debian and Ubuntu, mariadb-connector-c on Fedora and RHEL, mariadb-libs on Arch. PostgreSQL needs nothing extra.

3. Create the database role. Either let the role create its own database, or create an empty one yourself and leave the role without CREATEDB. §35.4 has both, and the SSL keys for a database on another host.

4. Edit /etc/hmailserver/hMailServer.ini. Fill in [Database]. Two rules catch people. Only ; starts a comment, and only at the start of a line. Text after a value on the same line is part of the value, so Type=PostgreSQL ; the backend matches no backend name. Write the port out: PostgreSQL wants 5432, MySQL and MariaDB want 3306. Leave AdministratorPassword alone.

5. Set the administrator password. sudo hmailserver --set-admin-password reads it from standard input with echo off and writes the hash into the file. This is the one step that runs as root, because the file is 0640 root:hmailserver.

6. Create the schema. sudo -u hmailserver hmailserver --create-database. Then, as root, make the stored-secrets key that second factors and the [Settings] secrets are sealed under, and export it at once: sudo hmailserver --create-stored-secrets-key, then sudo hmailserver --export-stored-secrets-key /root/hmailserver-stored-secrets.key. Keep that file with the database backups, stored apart from them. Without a key those secrets are stored as written, as before 6.3.4.

7. Check it before starting anything. sudo -u hmailserver hmailserver --check-config, as the service user and without --config, so the server has to find the configuration on its own. Database type: 0 means the Type key did not take. It is a report and not a validator: it returns 0 unconditionally, so read the output rather than its exit status.

8. Start it. sudo systemctl start hmailserver, then journalctl -u hmailserver -f.

A freshly created database already holds four listeners: SMTP on 25 and 587, POP3 on 110 and IMAP on 143, bound to every address. Since 6.3.4 the unit's first start, if it comes within a day of --create-database, gives them a self-signed certificate and optional STARTTLS, and makes the Internet IP range require TLS for authentication (SecureDefaults.md). Mail clients warn about a self-signed certificate, so replace it with ACME or your own before this faces the internet. The listeners and the certificate are database rows, not INI keys, so you change them over the API or the Control Deck's Ports and Certificates views.

9. Turn on administration. sudo hmailserver --set-setting RestApiPort=8080 (or another free port), leave RestApiBindAddress on loopback, and sudo systemctl restart hmailserver. Not by editing the file: since 6.3.4 the database is the settings store, and a [Settings] line edited after the first start is reported as HM5804 and not applied: the service cannot write the packaged file, so the line stays as you left it and the stored value is used. TLS is required unless the bind address is exactly 127.0.0.1, localhost or ::1, so tunnel over SSH rather than exposing it. §35.9 and §35.10 are the rest.

Post what --check-config printed and the last lines of journalctl -u hmailserver if a step stops. §35.16 lists the Linux-specific failures by symptom.