Install & Rollout Prep

1. Scope

The following sizing guidance is intended for WMail single-node or small production deployments. Actual capacity depends on mailbox count, concurrent IMAP connections, attachment size, retention period, anti-spam and antivirus policy, and backup window. Run delivery tests and load checks before full rollout.

2. Operating system and base software

• Recommended OS: Ubuntu 22.04 LTS / Debian 12 / Rocky Linux 9 / AlmaLinux 9, x86_64, kernel 5.10+.
• Docker deployment: Docker 24+ and Docker Compose v2.20+.
• Binary/systemd deployment: systemd, Nginx or equivalent reverse proxy, PostgreSQL 15+, Redis 7+.
• Mail components: Postfix, Dovecot, Amavisd-new, SpamAssassin; enable ClamAV based on security requirements.
• Time sync: enable NTP/chrony to avoid TLS, DKIM, license validation, and audit timestamp issues.

3. Server sizing

Scenario	CPU	Memory	System disk	Data/storage	Notes
Evaluation / test	2 vCPU	4 GB	50 GB SSD	Based on test data	For demos, validation, or a few test accounts. Keep ClamAV disabled.
Minimum production single node	2 vCPU	6 GB	80 GB SSD	Total mailbox quota × 1.2 or more	For low concurrency and small teams. If ClamAV is enabled, keep traffic low.
Recommended production single node	4 vCPU	8 GB	100 GB SSD	Dedicated SSD/NVMe data disk	For normal business production with backups, monitoring, DKIM/DMARC/SPF.
Recommended production with ClamAV	4 vCPU	12 GB	100 GB SSD	Dedicated SSD/NVMe with scan temp space	More stable when ClamAV, SpamAssassin, Amavis, database, and Redis run on the same host.
Medium/large or heavy attachments	8 vCPU+	16 GB+	200 GB SSD	Dedicated data disk/object storage/backup disk	For more users, larger attachments, or higher concurrency. Split database, Redis, storage, and scanning services when needed.

Rule of thumb: enabling ClamAV requires an extra 2-4 GB memory. For production on the same host as PostgreSQL, Redis, and the mail queue, start from 4 vCPU / 12 GB. Use 8 vCPU / 16 GB or split scanning services when attachment scanning peaks are high.

4. ClamAV and anti-spam configuration

• Keep ClamAV disabled during the first base deployment, then enable it after core send/receive, DNS, TLS, and license checks pass.
• Before enabling ClamAV, confirm clamd is reachable, freshclam can update virus definitions, and the virus database plus scan temp directory have stable storage.
• Set an attachment scan limit, such as 25 MB to start. Large attachments can be skipped, quarantined, or scanned asynchronously based on business policy.
• The first ClamAV startup may spend several minutes downloading virus definitions. Allow enough startup time in rollout scripts and health checks.
• With SpamAssassin + ClamAV enabled, messages pass through Amavis content filtering and latency will increase. Monitor queue length, scan duration, CPU load, and memory usage.
• For high traffic, run ClamAV/Amavis on dedicated nodes, or at least assign independent resource limits and restart policies to the scanning containers.

5. Disk, backup, and capacity planning

• Do not put heavy mailbox data on the system disk. Place /data, Maildir, attachments, logs, and backups on dedicated data disks.
• Size mailbox storage as total licensed mailbox quota × 1.2-1.5, plus growth headroom.
• Size backup storage for full plus incremental backups within the retention window, usually 1-3× effective data size.
• Reserve at least 20-50 GB for logs and queues; plan more for heavy attachment traffic.
• Use SSD/NVMe in production. Avoid low-IOPS disks for PostgreSQL, Redis, and hot Maildir data.

6. Network, domain, and ports

• Prepare a fixed public IP and configure PTR/rDNS to protect sender reputation.
• Required DNS normally includes MX, A/AAAA, SPF, DKIM, and DMARC. Validate delivery with a test domain before launch.
• Common ports: 25 inbound SMTP, 465/587 submission, 993 IMAP TLS, 995 POP3 TLS if enabled, and 80/443 for Web and certificate validation.
• If your cloud provider blocks outbound port 25, request unblocking early or use an outbound SMTP relay.
• Production deployments must enable TLS certificates and confirm server time, certificate chain, and domains match.

7. Database, Redis, and deployment mode

• Docker Compose is suitable for fast single-node delivery. In production, pin image versions, mount persistent directories, and configure restart policies.
• Binary/systemd deployment is suitable when PostgreSQL, Redis, Nginx, and operations tooling already exist.
• PostgreSQL 15+ is recommended. Enable scheduled backups, slow-query observation, and disk alerts.
• Redis 7+ is recommended. Configure password, persistence policy, and memory limits so cache usage does not exhaust host memory.
• As accounts, audit logs, or delivery volume grow, split PostgreSQL and Redis first, then split scanning and storage services.

8. Pre-install checklist

1. License, authorized domains, deployment mode, and installer source are confirmed.
2. Server sizing, data disk, backup disk, snapshot, or offsite backup strategy are ready.
3. Firewall, security groups, port access, NTP, and DNS records are prepared.
4. Database, Redis, initial admin password, and SMTP/IMAP/POP3 exposure policy are decided.
5. ClamAV enablement is decided; if enabled, memory, virus database updates, and scan temp space are confirmed.
6. TLS certificate, reverse proxy configuration, and rollback plan are ready.

9. Installation steps

Docker Compose

1. Download the delivery package and extract it on the target host.
2. Copy the environment template and fill domain, database password, Redis password, ports, license, and security switches.
3. Run docker compose pull and docker compose up -d.
4. Wait until database, Redis, backend, Web, mail components, and optional ClamAV health checks pass.
5. Sign in to the admin console and finish license activation, domain sync, DNS checks, and test delivery.

Binary/systemd

1. Prepare PostgreSQL, Redis, Nginx, TLS certificate, and runtime user.
2. Upload wmail-server and configuration files, then create data, log, attachment, and backup directories.
3. Configure the systemd service and environment variables, then run the pre-start checks.
4. Start the service and check /health, logs, database connection, Redis connection, and mail component status.
5. Configure reverse proxy and HTTPS, then complete rollout validation in the admin console.

10. Troubleshooting

• Startup failure: check environment variables, database/Redis connectivity, port conflicts, and data directory permissions.
• Login or license issue: check server time, authorized domains, network access, and license service connectivity.
• Send failure: check outbound 25/465/587 policy, PTR/rDNS, SPF/DKIM/DMARC, and mail queues.
• Receive failure: check MX, inbound 25, firewall, security groups, and Postfix/Dovecot status.
• ClamAV starts slowly or consumes memory: check virus database download status, reserve memory for clamd, and split scanning nodes if needed.
• Slow download or offline deployment: use an intranet mirror or contact support for an offline delivery package.

Before production launch, run at least one internal delivery test, one restore drill, and one license lease/heartbeat verification.

Usage Config & Launch Checks

1. License activation

1. Purchase or obtain a license from the licensing portal.
2. In the admin console, go to Platform Settings → License Management and activate or sync the license.
3. Confirm the license is active and the required local permissions are enabled for capabilities such as SMTP/IMAP/POP3, shared mailbox, SSO/LDAP, or AI.

2. Authorized domains and DNS

• Sync the authorized domains from the license first. Business domains are not added manually in the admin UI.
• In Platform Settings → Domain Management, run DNS checks, ownership verification, or generate Nginx configuration.
• Complete SPF / DKIM / DMARC and other required DNS records based on the deployment design.

3. Protocol and login configuration

• SMTP / IMAP / POP3 endpoints, ports, and encryption modes must follow the current deployment instance configuration rather than fixed website examples.
• If third-party client access is required, confirm the protocol services are enabled in the WMail admin console.
• If 2FA, SSO, or LDAP is required, configure it in the admin console first and validate the login path with test accounts.

4. Runtime and compliance checks

• Use request logs, health checks, and Prometheus metrics to confirm runtime behavior.
• If outbound SMTP relay is used, complete both test connection and test send.
• Before full rollout, run internal test delivery and verify audit logs, anti-spam policy, and backup recovery behavior.

Run internal test sends before full rollout.