Documentation & Resources

Comprehensive guides and references for Mail Server Factory

🚀

Getting Started

New to Mail Server Factory? Start here with installation and first deployment.

Overview Installation Quick Start
⚙️

Configuration

Learn about JSON configuration system, variables, and validation.

Configuration System File Structure Variables
🚢

Deployment

Understand the deployment pipeline and remote execution model.

Deployment Process Docker Stack Verification
🏗️

Architecture

Explore the system architecture and component design.

System Architecture Components Execution Flow
📧

Mail Server Components

Detailed information about each mail server component.

Postfix Dovecot Rspamd ClamAV
💻

Development

Build system, testing infrastructure, and contribution guidelines.

Build System Testing Supported Distributions
🔌

Connection API

12 connection types for flexible deployment across platforms.

Connection Types Connection Pool Cloud Providers
🏢

Enterprise Features

Security, performance, monitoring, and logging capabilities.

Security Performance Monitoring
📚

Reference

CLI reference, API documentation, and troubleshooting guides.

CLI Reference API Reference Troubleshooting

What is Mail Server Factory

Mail Server Factory is a Kotlin-based automation tool that deploys complete, production-ready mail server stacks on remote Linux servers. Users provide JSON configuration files that specify target hosts, mail accounts, and service parameters. The system then performs remote installation, Docker container deployment, database initialization, and mail account creation via SSH.

Deployed Components

  • Postfix (SMTP sending on port 465)
  • Dovecot (IMAPS receiving on port 993)
  • Rspamd (anti-spam filtering)
  • ClamAV (anti-virus scanning)
  • PostgreSQL (user database)
  • Redis (Rspamd caching)

All services run in isolated Docker containers with automated security, monitoring, and performance optimization.

Installation Methods

Web Installer (Recommended)

Quickest setup for production use:

curl -fsSL https://raw.githubusercontent.com/Server-Factory/Utils/master/web_installer.sh | /bin/bash

Local Installer

For development or customized installation:

./installer.sh [install_path]

Manual Build

For development and source code modifications:

git clone --recurse-submodules
./gradlew assemble

System Requirements

Local Machine

  • Java 17 or higher (OpenJDK recommended)
  • Linux, macOS, or Windows with bash
  • Internet access for downloading dependencies

Target Server

  • Modern Linux distribution (12 supported distributions)
  • SSH access with key-based authentication
  • Docker support (will be installed if missing)
  • Root/sudo access for system modifications
  • Ports 465 (SMTP) and 993 (IMAPS) accessible
  • SELinux disabled or in permissive mode

Configuration System

Mail Server Factory uses a JSON-based configuration system with variable substitution and file inclusion. The configuration defines everything about your mail server deployment.

Key Features

  • Hierarchical Configuration: JSON files can include other JSON files
  • Variable Substitution: Dynamic variable resolution using `${CONTEXT.KEY}` syntax
  • Type-Safe Parsing: Configuration parsed into strongly-typed Kotlin classes
  • Validation: Comprehensive validation of emails and passwords
  • Merging: Multiple configuration files combined into final config

Basic Configuration Structure

{
  "name": "Mail Server Configuration",
  "remote": {
    "hostname": "mail.example.com",
    "username": "admin",
    "port": 22
  },
  "includes": [
    "Includes/Common.json"
  ],
  "variables": {
    "SERVER": {
      "hostname": "mail.example.com"
    }
  }
}

Variable Substitution

Variables use the format `${CONTEXT.SUBCONTEXT.KEY}` and can reference other variables:

"certificate_endpoint": "https://${PROXY.HOSTNAME}:8080/api/v1/certificate"

Deployment Process

The deployment follows a sequential flow through four main stages:

1

Initialization

Parse configuration, validate accounts, establish SSH/Docker/DB connections

2

Installation

Install software packages and dependencies on remote server

3

Docker Deployment

Deploy Docker containers for mail stack services

4

Database Setup

Initialize PostgreSQL database and create mail accounts

Running a Deployment

mail_factory config.json

Example Configurations

The Examples/ directory contains pre-configured files for all supported distributions:

  • Ubuntu_22.json - Ubuntu 22.04 LTS
  • Debian_12.json - Debian 12 Bookworm
  • RHEL_9.json - RHEL 9
  • Fedora_Server_41.json - Fedora Server 41
  • And 8 more distributions...

Mail Server Components

Postfix (Mail Sending)

SMTP server responsible for outgoing email delivery. Configured for:

  • SMTPS on port 465
  • TLS encryption
  • Virtual domain hosting
  • Integration with Dovecot for authentication

Dovecot (Mail Receiving)

IMAP/POP3 server for incoming email and mail storage. Features:

  • IMAPS on port 993
  • Maildir storage format
  • PostgreSQL authentication backend
  • SSL/TLS support

Rspamd (Anti-Spam)

Advanced spam filtering system:

  • Real-time spam scanning
  • Machine learning filters
  • Web UI on localhost:11334
  • Redis integration for caching

ClamAV (Anti-Virus)

Virus scanning for email attachments:

  • Real-time virus database updates
  • Integration with Rspamd
  • Automatic quarantine of infected files

Database Services

PostgreSQL: User authentication, domains, aliases storage

Redis: Rspamd caching and learning data

Testing Infrastructure

Mail Server Factory includes comprehensive automated testing across 12 Linux distributions using QEMU virtualization:

Test Coverage

47
Total Tests
100%
Pass Rate
12
Distributions
85%+
Code Coverage

Supported Distributions

Debian-based

  • Ubuntu 22.04, 24.04
  • Debian 11, 12

RHEL-based

  • RHEL 9
  • AlmaLinux 9
  • Rocky Linux 9
  • Fedora 38-41

SUSE-based

  • openSUSE Leap 15.6

Security Features

Enterprise-grade security built into every deployment:

Authentication & Encryption

  • AES-256-GCM encryption for sensitive data
  • SSH key-based authentication (no passwords)
  • TLS certificate generation with self-signed CA
  • SSL/TLS enforcement for mail protocols

Password Policies

  • MEDIUM strength requirements enforced
  • Minimum length and complexity rules
  • Password hashing before database storage

System Security

  • Container isolation for all services
  • Audit logging for all operations
  • Session management with correlation IDs
  • Regular security updates via Docker

CLI Reference

Basic Usage

mail_factory [options] configuration.json

Common Options

--help, -h Display help message
--version, -v Show version information
--debug Enable verbose output
--dry-run Preview command without executing
--jar <path> Specify JAR location explicitly
--installation-home <path> Override installation directory

Environment Variables

JAVA_HOME Java installation directory
JAVA_OPTS JVM options (e.g., -Xmx4g)
MAIL_FACTORY_HOME Override JAR search location

Exit Codes

0 Success - deployment completed
2 Java not found or wrong version
3 JAR file not found
4 Invalid command line arguments
5 Configuration file not found

Connection API - 12 Connection Types

Mail Server Factory provides a comprehensive connection abstraction layer supporting 12 different connection types for maximum deployment flexibility.

Standard Connections

1. SSH Connection

Standard SSH protocol for remote server access with key-based authentication.

  • Command execution and file transfer
  • Connection pooling for performance
  • Automatic reconnection handling

2. Docker Connection

Direct Docker daemon communication for container management.

  • Container lifecycle operations
  • Volume and network management
  • Image pull and build operations

3. Kubernetes Connection

Kubernetes cluster management and orchestration.

  • Pod and deployment operations
  • Service mesh integration
  • ConfigMap and Secret management

Cloud Provider Connections

4. AWS SSM Connection

AWS Systems Manager Session Manager for secure EC2 access.

  • No inbound ports required
  • IAM-based authentication
  • Session logging and auditing

5. Azure Serial Console

Azure VM serial console for emergency access.

  • Access when SSH unavailable
  • Boot diagnostics integration
  • Direct VM console access

6. GCP OS Login

Google Cloud Platform OS Login with IAM integration.

  • IAM-based SSH access
  • Two-factor authentication
  • Centralized user management

Specialized Connections

7. Libvirt Connection

KVM/QEMU virtualization management.

  • VM lifecycle operations
  • Virtual network management
  • Storage pool operations

8. Custom Protocol

Extensible connection interface for custom protocols.

  • Plugin architecture
  • User-defined connection logic
  • Protocol-agnostic design

9. Database Connection

Direct database access and management.

  • SQL execution and migrations
  • Connection pooling
  • Transaction management

10. File System Connection

Local and remote file system operations.

  • NFS and CIFS support
  • File synchronization
  • Mount management

11. Cloud Provider

Multi-cloud provider abstraction.

  • AWS, Azure, GCP unified interface
  • Resource provisioning
  • Cost optimization

12. Container Runtime

OCI-compliant container runtime support.

  • Podman, containerd, CRI-O
  • Runtime abstraction layer
  • Cross-runtime compatibility

Connection Pool Management

All connections are managed through the ConnectionPool which provides:

  • Connection Reuse: Efficient connection lifecycle management
  • Automatic Reconnection: Handles transient failures gracefully
  • Thread Safety: Concurrent connection access
  • Resource Cleanup: Automatic disposal and cleanup
  • Health Monitoring: Connection health checks

Usage Example

// Create SSH connection
val sshConnection = SSHConnection(hostname, username, port)

// Execute command
val result = sshConnection.execute("docker ps -a")

// Connection automatically managed by ConnectionPool
// No manual cleanup required

Troubleshooting

Common Issues

SSH Connection Failed

Cause: SSH key not configured or network issue

Solution:

  • Verify SSH key-based authentication: ssh user@target
  • Check network connectivity: ping target-hostname
  • Ensure SSH server is running on port 22

Docker Deployment Failed

Cause: Docker not installed or conflicting containers

Solution:

  • Check Docker installation: docker --version
  • Remove conflicting containers: docker ps -a
  • Verify Docker service status: systemctl status docker

Configuration Validation Failed

Cause: Invalid email format or weak password

Solution:

  • Verify email format: user@domain.com
  • Check password strength (minimum 8 characters, mixed case, numbers)
  • Validate JSON syntax using online validator

Mail Account Creation Failed

Cause: Database connection issue or account validation error

Solution:

  • Check PostgreSQL container status: docker ps | grep postmaster_db
  • Verify database connectivity: docker exec postmaster_db psql -l
  • Review deployment logs for specific error messages

Getting Help

  • Check deployment logs in ${INSTALLATION_HOME}/
  • Enable debug mode: mail_factory --debug config.json
  • Review configuration files for syntax errors
  • Consult GitHub issues for known problems