Installation

#Before you begin

Install Alt8Mail on a clean Debian 12 host after completing the requirements checklist. Confirm the public IPv4 address, DNS A records, provider firewall and port 25 policy first. The installer is a root-level operation that changes the mail, web, database, cache, firewall and systemd configuration.

Keep a console session open until the final health check passes. Do not run an unrelated mail or web stack on the same host.

#The managed installation terminal

The commands below are served by this site and can be updated by an Alt8Mail administrator from Control desk → Settings → Installation commands. Treat them as the current published procedure, not an immutable script.

$ git clone --depth 1 https://github.com/CryptRoute/Alt8Mail.git
cd Alt8Mail

$ sudo bash install.sh \
  --domain a8m.example.com \
  --hostname mail.a8m.example.com \
  --admin-email owner@a8m.example.com \
  --non-interactive

#Alternative: tagged release bundle

For a controlled production rollout, download a tagged release bundle and its checksum from the project releases page. Verify the checksum on the target host before extracting anything.

scp alt8mail-<version>.tar.gz alt8mail-<version>.tar.gz.sha256 root@SERVER_IP:/root/
ssh root@SERVER_IP
cd /root
sha256sum -c alt8mail-<version>.tar.gz.sha256
tar -xzf alt8mail-<version>.tar.gz
cd alt8mail-<version>
sudo bash install.sh --help

The release bundle contains the binaries, public assets, admin assets, migrations, deployment templates, scripts and installer. It does not contain runtime data or secrets. The installer validates the release version and fails if the expected server binary is missing.

If you install from a source checkout instead, the installer can build the release when bin/a8m-server is absent. That path requires Go; the installer provisions it when needed.

#Installer flags

The installer supports both interactive and non-interactive operation. Use --help on the extracted release to see the exact flags for your version.

Keep the installer log at /var/log/a8m-install.log. If the operation stops, inspect that log before retrying.

#What the installer does

The order matters when you plan a maintenance window.

1. Preflight. Checks root, Debian 12, required arguments, hostname and public IPv4 reachability.
2. Host preparation. Installs base packages, sets UTC, writes the hostname and mail name, and may create swap.
3. Mail and web stack. Installs and configures PostgreSQL, Redis, Dovecot, Postfix, Rspamd, ClamAV, nginx, certbot and supporting packages.
4. Database. Creates the Alt8Mail database, roles, extensions and schema migrations.
5. Release installation. Installs the release under /opt/a8m/releases/<version>, updates the current symlink, installs the updater and writes /etc/a8m/app.env and /etc/a8m/control.env.
6. TLS. Requests a certificate or falls back to a self-signed pair. Installation does not configure DNS.
7. Services. Installs systemd units, starts the stack, seeds the first tenant and owner, provisions the first mailbox and creates the System Control superadmin.
8. Firewall. Resets UFW and opens the supported service ports. Review the resulting rules before exposure.
9. Health checks. Probes the application services, nginx, Postfix and System Control. The installer exits non-zero if the supported checks fail.

The installer preserves generated secrets across re-runs and can be used for repair. It is not the application upgrade path. Use alt8mail-update for an installed release.

#First sign-in

The installer writes one-time bootstrap credentials to root-owned files. Capture them before you leave the console, then remove the files after you have stored the credentials safely.

The System Control plane is root-equivalent. Restrict port 8808 to a management network or VPN before sharing the host with users.

#Complete domain setup

Installation alone does not make a domain mail-ready. In Customer Admin:

1. Create or verify each sending and receiving domain.
2. Publish the ownership TXT, MX, SPF, DKIM and DMARC records shown by Alt8Mail.
3. Wait for DNS propagation, then rerun domain verification.
4. Create users and mailboxes, or import them through the migration workflow.
5. Review tenant policies for password rules, MFA, external forwarding, IMAP/POP3, attachment limits and retention.
6. Send test mail in both directions and confirm the sender-trust panel shows passing authentication.

A domain that fails DKIM alignment or DMARC will not be fully mail-ready even when the web interface works.

#TLS follow-up

If the installer used a self-signed certificate because DNS was not ready:

1. Correct the A/AAAA records and port 80 reachability.
2. Issue or install a trusted certificate through System Control → Security → TLS certificates.
3. Assign the certificate to nginx, Postfix and Dovecot.
4. Verify with a browser and a mail client before announcing the service.

Certificate renewal is operationally critical. Monitor expiry and the renewal logs rather than assuming ACME always succeeds.

#OnlyOffice

The installer does not install Docker. Office remains disabled until Docker and the Office agent are healthy. Use System Control → Infrastructure → Office to configure a local or remote OnlyOffice deployment, preflight it, and start it. OnlyOffice licensing is separate from the Alt8Mail license.

Without a healthy Office runtime, the rest of the workspace continues to work; Office files open as files rather than in the editor.

#Verification checklist

Run these checks before handing the system to users:

systemctl --failed
systemctl status a8m-server a8m-admin alt8mail-control nginx postfix dovecot --no-pager
curl -fsS http://127.0.0.1:8080/api/health
curl -fsS http://127.0.0.1:8081/api/health
curl -kfsS https://127.0.0.1:8808/healthz
postfix check
nginx -t
/opt/alt8mail/bin/alt8mail-control doctor

Also verify that a test message can arrive from an external mailbox, that an outbound message is queued and delivered, and that a reply reaches both the webmail user and the recipient's provider without a TLS or authentication warning.

#Next steps

• Configure the customer admin policies and complete the security hardening checklist.
• Plan ongoing service checks, backups and updates with Operate.
• Move existing mail with Mailbox migration.
• Keep Troubleshooting available during the first maintenance window.