Installation

This guide walks you through the complete installation process for CeyMail Mission Control, including system requirements, DNS preparation, the interactive installer, the post-install wizards, and troubleshooting.

System requirements

Required ports

The installer configures UFW automatically with these rules:

Step 1: Configure DNS before installation

The installer provisions SSL certificates via Let's Encrypt for your dashboard subdomain. Let's Encrypt validates domain ownership by connecting to your server on port 80, so DNS must resolve to your server before you run the installer.

You need two A records -- one for the mail hostname and one for the dashboard:

Type:  A
Host:  mail.example.com
Value: 203.0.113.10    (your server IP)
TTL:   300

Type:  A
Host:  mc.example.com
Value: 203.0.113.10    (your server IP)
TTL:   300

Use a low TTL (300 seconds) so you can iterate quickly if something goes wrong.

Verify DNS is resolving correctly:

# Should return your server IP
dig +short mail.example.com

# Should return your server IP
dig +short mc.example.com

Step 2: Run the installer

Connect to your server via SSH as root and run:

curl -sSL https://ceymail.com/install | sudo bash

Interactive prompts

The installer will ask for three values:

1. Mail domain (e.g., mail.example.com) -- The hostname for your Postfix/Dovecot mail server
2. Dashboard subdomain (e.g., mc.example.com) -- Where Mission Control will be served. Defaults to mc. + your mail domain if left blank
3. Let's Encrypt email (e.g., you@gmail.com) -- Must be on an external domain, not the domain you are setting up

You can also run the installer non-interactively by setting environment variables:

MAIL_DOMAIN=mail.example.com \
DASHBOARD_DOMAIN=mc.example.com \
CERTBOT_EMAIL=you@gmail.com \
curl -sSL https://ceymail.com/install | sudo bash

What gets installed

The setup script performs these steps in order:

1. Web server detection -- Detects Nginx or Apache (installs Nginx if neither is found)
2. System configuration -- Sets hostname, upgrades packages (first run only)
3. Firewall -- Configures UFW with required port rules
4. Dependencies -- Installs Node.js 22, MariaDB, Certbot, DNS tools, Unbound (local DNS resolver)
5. Databases -- Creates ceymail and ceymail_dashboard databases with tables, generates credentials
6. DH parameters -- Generates 2048-bit DH parameters for Postfix TLS
7. Application -- Downloads the latest release tarball (SHA256-verified) and installs to /opt/mission-control
8. Dashboard deployment -- Deploys the Next.js dashboard as a systemd service on port 3000
9. Reverse proxy -- Generates Nginx/Apache config with SSL, rate limiting, security headers, and WebSocket support
10. SSL certificates -- Provisions Let's Encrypt certificates for the dashboard domain (if DNS is ready)

The process typically completes in 3-5 minutes. On completion, you will see:

  Dashboard:  https://mc.example.com
  Web server: nginx
  Server IP:  203.0.113.10

  Next steps:
  1. Open https://mc.example.com in your browser
  2. Complete the setup wizard (create your admin account)
  3. Run the install wizard (Settings > Install Mail Services)
  4. Add DNS records shown by the install wizard

Step 3: Complete the Welcome Wizard

Open your dashboard URL in a browser. You will be redirected to /welcome -- the setup wizard that finalizes the dashboard configuration.

Step 3a: Database setup

The wizard verifies the MariaDB connection using the credentials generated during installation. If the setup script already provisioned the database (which it does by default), this step is automatic.

Step 3b: Create admin account

Create your dashboard administrator account with a username and password. This account is used to log into Mission Control and is separate from mail user accounts.

Step 3c: Complete

Once the admin account is created, you are redirected to the login page. Log in with your new credentials.

Step 4: Run the Install Wizard

After logging in, navigate to the Install page (accessible from the sidebar). The install wizard configures all mail services through a guided, multi-step process:

Each step runs automatically and shows progress in real time. If a step fails, you can retry it without starting over.

Verification

After completing both wizards, verify your installation:

# Check all CeyMail services
ceymail status

Expected output:

CeyMail Mission Control v0.1.65

Services
  Dashboard          running
  Postfix            running
  Dovecot            running
  OpenDKIM           running
  MariaDB            running
  SpamAssassin       running
  SA Milter          running
  AI Filter          not installed

You can also verify individual services:

# Test SMTP submission
openssl s_client -connect mail.example.com:587 -starttls smtp

# Test IMAPS
openssl s_client -connect mail.example.com:993

Firewall configuration

The installer configures UFW automatically. If you need to adjust the firewall manually:

sudo ufw allow 22/tcp    # SSH
sudo ufw allow 25/tcp    # SMTP
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 587/tcp   # Submission
sudo ufw allow 993/tcp   # IMAPS
sudo ufw --force enable

Re-running the installer

The setup script is idempotent -- it is safe to re-run at any time. On subsequent runs it will:

• Reuse existing configuration from /etc/ceymail.conf
• Skip system package upgrades
• Reuse existing database credentials
• Download the latest release
• Re-deploy the dashboard
• Retry SSL if it was previously skipped

# Re-run on the server
sudo bash /opt/mission-control/setup.sh

# Or download and run the latest version
curl -sSL https://ceymail.com/install | sudo bash

Troubleshooting

SSL certificate not obtained

If the installer reports that DNS is not pointing to your server, SSL is skipped and the dashboard runs on HTTP. Verify your A records:

dig +short mc.example.com @8.8.8.8
dig +short mail.example.com @8.8.8.8

Both should return your server IP. Once DNS resolves correctly, re-run the setup script to obtain certificates.

Port 25 blocked by hosting provider

Some cloud providers (AWS, GCP, Oracle Cloud) block outbound port 25 by default. You will need to request an unblock through their support portal, or configure an SMTP relay through the dashboard (Settings > Integrations).

MariaDB not starting

Check the MariaDB logs:

sudo journalctl -u mariadb -n 50 --no-pager

Common causes include corrupted system tables after a failed purge/reinstall cycle. The setup script handles most recovery scenarios automatically on re-run.

Dashboard not loading

Verify the dashboard service is running:

sudo systemctl status ceymail-dashboard

Check its logs:

sudo journalctl -u ceymail-dashboard -n 50 --no-pager