Guided Installation Manual · v1.2.4

From a Fresh Host to Production Mail Flow in 8 Steps

A mail server depends more on its network than on its hardware: if Port 25 is blocked or Reverse DNS (PTR) is missing, messages will not deliver regardless of CPU power. This guide walks you in strict order from pre-flight checks through setup, Dual-Key DKIM, TLS, and mobile onboarding to your first verified delivery.

Jump to 8-Step Tutorial Troubleshooting by Symptom Live DNS & rDNS Inspector

Chapter 01

How SharpMailserver Boots and Reaches Production

SharpMailserver packages ESMTP, IMAP4rev2, JMAP, Exchange ActiveSync, CalDAV/CardDAV, ManageSieve, SpamGuard, the GoBD WORM archive, the Admin Cockpit (/admin/), and the SharpMail Webmail PWA (/mail/) into a single memory-safe binary (~40 to 90 MB idle RAM). Nothing is downloaded from GitHub at first boot, and no external NSSM wrappers, Redis, Rspamd, or separate webmail containers are required.

Order Matters: Verify Chapter 02 (Port 25 & Reverse DNS at your provider) before running a single command, then follow Chapter 04 for your platform and consult Chapter 06 whenever an output differs from the expected state.

STEP 01-02Install & Sign InInstall SHA-256-verified package, open ports, and sign in to /admin/.

STEP 03-05Domain, TLS & Dual DKIMIssue ACME/PFX certificate and publish both RSA-2048 & Ed25519 DNS records.

STEP 06-07Harden & Connect DevicesEnable SpamGuard, Dual-Stack IPv6, GoBD, and 1-click QR/WhatsApp profiles.

STEP 08Verify Mail FlowRun Outbound MX/DANE tester + round-trip test via Message Trace.

Chapter 02

System & Network Prerequisites (Pre-Flight Checklist)

Tick off all 6 items below before installing. Four of them are controlled outside the server in your hosting or DNS control panel.

1. Static public IPv4 address (plus optional IPv6): Residential dynamic IPs are listed on Spamhaus PBL; either use a business static IP/VPS or configure an outbound smart host. 2. TCP Port 25 open in BOTH directions: Some cloud providers block outbound TCP 25 on new accounts until unlocked in their console. 3. Reverse DNS (PTR) matches for BOTH IPv4 and IPv6: Both your IPv4 and IPv6 PTR records must resolve to your exact SMTP hostname (e.g. mail.company.com), matching forward A/AAAA records. 4. Control over your domain's DNS zone: Required to publish A/AAAA, MX, SPF, dual DKIM selectors (s2026 + s2026ed), DMARC, MTA-STS, and optional TLSA/BIMI. 5. Inbound firewall ports allowed on host & gateway: Required: TCP 25, 443, 465, 587, 993. Optional: TCP 80 (ACME HTTP-01), 143 (IMAP STARTTLS), 4190 (ManageSieve). 6. Outbound UDP/TCP 53 (DNS) & TCP 443 (ACME): Used for DNSSEC/DANE/SPF resolution and automated Let's Encrypt renewals.

Port	Protocol / Service	Direction	Requirement & Guidance
`25 / TCP`	ESMTP (MX Server-zu-Server + STARTTLS/DANE)	Inbound & Outbound	Required - Essential for receiving and delivering internet mail.
`443 / TCP`	HTTPS (`/admin/`, `/mail/`, JMAP, ActiveSync, CalDAV/CardDAV, MTA-STS)	Inbound (+ Outbound)	Required - Serves Webmail, Admin, Mobile Push, DAV, JMAP & ACME.
`465 / TCP`	SMTPS Submission (Implicit TLS, RFC 8314)	Inbound	Required - Preferred implicit TLS submission port (RFC 8314).
`587 / TCP`	SMTP Submission (STARTTLS)	Inbound	Required - Standard STARTTLS submission for Outlook, printers & ERPs.
`993 / TCP`	IMAPS (`IMAP4rev2` Implicit TLS)	Inbound	Required - Encrypted IMAP4rev2 with zero-polling IDLE push.
`80 / TCP`	HTTP (ACME `HTTP-01` & Autoconfig Redirect)	Inbound	Recommended (optional when using TLS-ALPN-01 or gateway PFX).
`4190 / TCP`	ManageSieve (STARTTLS)	Inbound	Optional (Webmail visual Sieve editor already works over 443).
`143 / TCP`	IMAP (STARTTLS)	Inbound	Optional (prefer port 993 implicit TLS).

Deployment Size	CPU	RAM	Disk & Recommended Database
1 to 250 mailboxes	2 vCPU	1 - 2 GB RAM	NVMe/SSD · Embedded SQLite WAL + Zstandard (~40-90 MB server footprint).
250 to 2,500 mailboxes	4 vCPU	4 - 8 GB RAM	NVMe + optional Hybrid S3 · PostgreSQL 18 or Microsoft SQL Server (2019-2025).
2,500+ HA Cluster	8+ vCPU (2+ Nodes)	16+ GB RAM	Active-Active nodes on PostgreSQL 18 or SQL Server Always On + S3 Object Lock.

Chapter 03

Choosing Your Platform & Storage Backend

Every platform runs the exact same feature set. Choose the deployment method and SQL backend that match your operations team.

Platform	Method	Best suited for
Windows Server 2019 / 2022 / 2025 (x64)	`SharpMailserver-Setup-win-x64.msi` / `install.ps1`	Native Windows SCM Service without Docker or NSSM; ideal alongside Microsoft SQL Server or hMailServer migrations.
Linux (`x86_64` & `ARM64`)	`install.sh` · `.deb` · `systemd`	Lean non-root systemd daemon on Debian, Ubuntu LTS, RHEL/Rocky, or ARM64 servers.
Docker & Docker Compose	`sharpmailserver/server:1.2.4`	Reproducible container stacks across Linux hosts, Proxmox VMs, Synology, UGREEN, and Unraid.
macOS (Apple Silicon) & Kubernetes	`.tar.gz launchd` / `Helm v3`	Mac mini office servers (launchd) or horizontal Active-Active Kubernetes clusters.

Chapter 04

The 8-Step Tutorial: Install to First Verified Test Email

Select your target platform below. Each of the 8 steps states what it does, shows the exact command, confirms the expected result, and highlights the most common pitfall right where it happens.

STEP 01

Install the Service & Open Firewall Ports

Downloads the release package, verifies its SHA-256 digest, and registers the background service and persistent data directory.

# PowerShell als Administrator: Lädt .msi (v1.2.4), prüft SHA-256 & startet den Setup-Assistenten
irm https://sharpmailserver.com/install.ps1 | iex

# Optional: Prüfen, ob die Windows-Firewall die Mail- & HTTPS-Ports durchlässt
New-NetFirewallRule -DisplayName "SharpMailserver" -Direction Inbound -Protocol TCP -LocalPort 25,80,443,465,587,993,4190 -Action Allow

# Debian / Ubuntu / RHEL / macOS: Prüft SHA-256, fragt Domain/Hostname/Admin ab & aktiviert systemd
curl -fsSL https://sharpmailserver.com/install.sh | sudo bash

# Falls UFW aktiv ist, Pflichtports freigeben:
sudo ufw allow 25,80,443,465,587,993,4190/tcp

# Baut/zieht das SHA-256-verifizierte Image sharpmailserver/server:1.2.4 & legt docker-compose.yml an
curl -fsSL https://sharpmailserver.com/install.sh | sudo bash -s -- \
  --mode docker --domain firma.de --hostname mail.firma.de --admin admin@firma.de

Expected Result: The service is active, enabled on boot, and listening on HTTPS and mail ports.

Common Pitfall: If startup reports 'Address already in use', a pre-installed MTA (Postfix/Exim) or web server holds Port 25/80/443 -> see Chapter 06 (#sym-port-bind).

STEP 02

Verify Service Health & Sign In to /admin/

Confirm clean listener startup in the logs and sign in to the Admin Cockpit with the administrator credentials set during installation.

Get-Service SharpMailserver
# Im Browser öffnen: https://mail.firma.de/admin/ (oder lokal auf dem Server http://localhost/admin/)

sudo systemctl status sharpmailserver
sudo journalctl -u sharpmailserver -n 30 --no-pager
# Im Browser öffnen: https://mail.firma.de/admin/

docker compose ps
docker compose logs --tail=30 sharpmail
# Im Browser öffnen: https://mail.firma.de/admin/

Expected Result: The real-time dashboard at /admin/ opens and shows active listeners for SMTP, IMAP, and HTTPS.

STEP 03

Configure Mail Domain & Parallel Dual-Key DKIM

Open Domains & Routing -> Manage Domain in /admin/. SharpMailserver automatically provisions two parallel DKIM key pairs: RSA-2048 (selector s2026) and Ed25519 (selector s2026ed).

Best Practice: Publish BOTH TXT records in DNS once in Step 5; you can then switch signing modes (RSA-2048, Ed25519, or Dual-Sign) on the server instantly with zero DNS propagation wait.

STEP 04

Enable TLS Certificate (ACME Let's Encrypt or Gateway PFX)

Open Security & Certificates -> TLS & ACME. Once mail.company.com resolves to your host, request a Let's Encrypt certificate via HTTP-01 or TLS-ALPN-01 (port 443), or upload a .pfx/.pem certificate from your pfSense/SSL gateway.

Expected Result: 0 ms Dynamic SNI hot-reload activates the certificate immediately across HTTPS, SMTPS, IMAPS, and ManageSieve without restarting.

STEP 05

Publish DNS Records & Run Live DNS Verification

Copy the computed DNS records from the built-in DNS Advisor (or export the BIND zone file): MX, A/AAAA, SPF, both DKIM selectors (s2026 + s2026ed), DMARC, MTA-STS, TLS-RPT, and optional DANE TLSA (3 1 1) and BIMI.

Expected Result: Clicking 'Verify Live DNS' shows green pass badges for MX, SPF, both DKIM selectors, DMARC, and PTR.

Common Pitfall: Many DNS control panels append your domain automatically; enter s2026._domainkey as host rather than s2026._domainkey.company.com -> see #sym-dkim-dns.

STEP 06

Harden the Server Before Production

Register a Passkey (WebAuthn) or TOTP 2FA on your administrator account, keep SpamGuard thresholds at 4.5 / 9.0 with Smart Greylisting active, and enable GoBD WORM archiving on commercial domains.

Expected Result: Auto-ban protection, mandatory TLS before authentication, and outbound rate guards protect your IP reputation automatically.

STEP 07

Create First Mailbox & Connect Mobile Devices in 30 Seconds

Create your first user mailbox under Accounts & Lists, sign in at https://mail.company.com/mail/, and click 'Device Setup' to generate a QR code or messenger-safe 1-click onboarding link with a CMS-signed iOS/macOS profile or Exchange ActiveSync.

Expected Result: iOS displays a green 'Verified' badge on the profile and immediately syncs Mail, Calendars, Contacts, and Notes.

STEP 08

Confirm Inbound & Outbound Delivery via Live MX Tester & Message Trace

Run Diagnostics & Logs -> Outbound MX & DANE Tester against gmail.com or an external address, then send a real email from /mail/ and reply back to verify two-way flow.

Expected Result: Message Trace records Delivered over TLS 1.3 in both directions, and the external receiver headers show spf=pass, dkim=pass, and dmarc=pass.

Chapter 05

Running Behind pfSense / OPNsense, SSL Gateways & Reverse Proxies

When deploying behind pfSense, OPNsense, Sophos, or HAProxy, configure these three settings for accurate diagnostics and real client IP preservation:

Scenario	Recommended Setup
Split-DNS / Hairpin-NAT	Configure a Split-DNS host override in Unbound pointing mail.company.com to the internal LAN IP, or enable Pure NAT Reflection on your gateway.
HAProxy PROXY Protocol (v1/v2)	Enable PROXY protocol v1/v2 restricted to your trusted proxy CIDR so SPF and Auto-Ban see the true remote IP rather than the gateway IP.
Zentrales Gateway-Zertifikat	Sync your gateway's renewed .pfx/.pem certificate to SharpMailserver for ports 25/465/587/993; Dynamic SNI hot-reloads updated certificates with zero downtime.

Chapter 06

Troubleshooting by Symptom (From Error to Immediate Fix)

Click the symptom you observe below or paste part of the error message into the top-left filter box:

External port checker reports 'Blocked / Timeout' even though the service is running TCP 25 / 465 / 993 Timeout

Root Cause: Either both hosts sit behind the same pfSense/OPNsense firewall without Hairpin NAT (NAT Reflection), or your cloud provider's outer firewall still blocks Port 25.

Fix: Check Network Diagnostics inside /admin/ (which auto-detects co-hosted Hairpin NAT gateways) and verify that your outer cloud firewall allows TCP 25, 443, 465, 587, and 993.

Service fails to bind a port at startup Address already in use (:25 / :80 / :443)

Root Cause: A pre-installed MTA (Postfix, Exim, Sendmail) on Linux or IIS/Nginx/Apache already occupies Port 25, 80, or 443.

Fix: Inspect active listeners via 'sudo ss -tulpn' on Linux (disable unused postfix/exim) or 'Get-NetTCPConnection -State Listen' in PowerShell.

Outbound mail to Gmail, Microsoft 365, or major ISPs is rejected 550-5.7.25 / 550-5.7.1 PTR missing

Root Cause: Your host connects out over IPv6 on a dual-stack interface, while you only configured a PTR record for IPv4 and forgot the IPv6 PTR record.

Fix: Set matching PTR records for BOTH your IPv4 and IPv6 addresses in your hosting provider's panel to match Smtp:ServerHostName.

Live DNS Inspector does not find your published DKIM or DMARC TXT record NXDOMAIN s2026._domainkey

Root Cause: Many DNS control panels automatically append the zone apex, turning 's2026._domainkey.company.com' into 's2026._domainkey.company.com.company.com', or split long RSA-2048 strings with stray spaces.

Fix: Enter only the relative host label ('s2026._domainkey', 's2026ed._domainkey', '_dmarc') in your DNS panel, and verify via 'nslookup -type=txt s2026._domainkey.company.com'.

Let's Encrypt ACME fails to issue a certificate or browser shows a TLS warning ACME challenge failed

Root Cause: Either the A/AAAA DNS record for mail.company.com has not propagated yet, or Port 80/443 is intercepted upstream by another reverse proxy.

Fix: Use TLS-ALPN-01 when Port 443 reaches SharpMailserver directly, open Port 80 for HTTP-01, or import your reverse proxy's renewed certificate via PFX/PEM.

iPhone opens a WhatsApp / Teams onboarding link without immediately launching Settings profile install iOS In-App WebView

Root Cause: iOS restricts .mobileconfig system profile installation exclusively to Safari, whereas chat apps open links inside an embedded WebView first.

Fix: Tap the Safari compass icon ('Open in Safari') as guided on the onboarding page; preview crawlers never consume the one-time token.

Docker container restarts or cannot write to mounted host volume Access to path '/var/lib/sharpmail' denied

Root Cause: Strict host directory ownership or SELinux labels on RHEL/Rocky/Fedora block container writes to bind-mounted folders.

Fix: Use named Docker volumes or append ':Z' to bind mounts on SELinux-enforcing hosts.

Mail client cannot sign in over IMAP or SMTP 535 Authentication failed / TLS required

Root Cause: Either the client attempted plaintext login without TLS (blocked by RequireTlsForAuth), or 2FA is active on the account and an App Password is required for legacy IMAP/SMTP.

Fix: Configure Port 993 (SSL/TLS) and Port 465 (SSL/TLS) or 587 (STARTTLS) with the full email address as username, and generate a dedicated App Password when 2FA is enabled.

Chapter 07

Next Steps: 10-Second Upgrades, Backups & Migration

Once two-way mail flow is confirmed, your server is ready for production. Keep these three operational workflows handy:

# 1) Unterbrechungsfreies Update auf neue Versionen (erhält Konfiguration, Zertifikate & Postfächer):
# Linux / macOS:
curl -fsSL https://sharpmailserver.com/install.sh | sudo bash -s -- --update
# Windows PowerShell (Administrator):
irm https://sharpmailserver.com/install.ps1 | iex

# 2) Backup-Umfang (nur 2 Pfade sichern):
# - Konfigurationsdatei: appsettings.Production.json (inkl. Lizenz-Token)
# - Datenverzeichnis:    Storage:DataDirectory (inkl. SQLite WAL / Blobs / TLS-Zertifikate)
#   bzw. pg_dump / SQL Server Backup bei externem Datenbank-Cluster

Continue to Chapter 01: Architecture & Port Matrix -> Documentation Hub (/docs/) 1-Click hMailServer & IMAP Migration

Installation FAQ

Quick Answers Before First Boot

Does SharpMailserver require NSSM or Docker Desktop on Windows Server?

No. Unlike servers that require NSSM service wrappers on Windows, SharpMailserver registers natively with the Windows Service Control Manager (SCM) via our official .msi installer without Docker Desktop, WSL2, or Hyper-V.

Does SharpMailserver need internet access at first boot to download its WebUI or spam rules?

No. The entire Admin Cockpit (/admin/), SharpMail Webmail PWA (/mail/), SpamGuard engine, and all protocol listeners are self-contained inside the SHA-256-verified package, enabling 100% offline/air-gapped startup.

Why must Reverse DNS (PTR) match before sending the first test email?

Major receivers such as Gmail, Microsoft 365, and European ISPs verify that both your public IPv4 and IPv6 addresses resolve via PTR back to your exact SMTP EHLO hostname (e.g. mail.company.com). Missing IPv6 PTR records on dual-stack hosts are the #1 cause of 550-5.7.25 rejections.

How do in-place upgrades work once the server is in production?

Run curl -fsSL https://sharpmailserver.com/install.sh | sudo bash -s -- --update on Linux/macOS or irm https://sharpmailserver.com/install.ps1 | iex on Windows (or use the 1-click updater inside /admin/). Your appsettings.Production.json, TLS certificates, DKIM keys, and mail store are preserved automatically.