How to Install Mailpit on Ubuntu VPS: The Complete Production-Ready Guide

When building and testing web applications, capturing outbound emails without accidentally sending them to real users is critical. Mailpit is a fast, lightweight, and modern email testing tool that acts as a dummy SMTP server with a beautiful web interface.

This guide walks you through installing Mailpit on an Ubuntu VPS, configuring it to start automatically on boot, protecting it behind Nginx with an SSL certificate, enabling persistent database storage, and securing the web interface with authentication.

Install Mailpit Binary

The cleanest way to install Mailpit on Ubuntu is using their official automated shell script. This automatically detects your system architecture and places the binary into your system path.

bash <(curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh)

Set Up a Dedicated System User

For security, you should never run backend services as the root user. Create a isolated system user with no login permissions specifically for Mailpit:

sudo useradd -r -M -s /bin/false mailpit

Configure Persistent Database Storage

By default, Mailpit stores emails in temporary volatile memory (RAM), meaning your testing emails will disappear every time the VPS reboots. To keep your emails intact, we will set up a permanent SQLite database directory and give the mailpit user ownership.

# Create the storage directory
sudo mkdir -p /var/lib/mailpit

# Assign ownership to the mailpit user
sudo chown -R mailpit:mailpit /var/lib/mailpit

Secure the UI with Basic Authentication (Nginx-Friendly Method)

Since your Mailpit dashboard will be accessible via a public domain, you need to lock it down so strangers cannot view your application's test emails.

Instead of installing heavy Apache tools just to generate a password, use the native openssl utility already present in Ubuntu to create an encrypted authentication file.

Run the following command (replace admin and password with your desired username and secure password):

echo "admin:$(openssl passwd -1 password)" | sudo tee /var/lib/mailpit/auth

# Restrict file permissions for safety
sudo chown mailpit:mailpit /var/lib/mailpit/auth
sudo chmod 600 /var/lib/mailpit/auth

Note on Changing Passwords Later: If you ever need to change your password down the road, simply rerun the exact command block above with your new password string and restart the Mailpit service.

Create the Systemd Service for Autostart

To ensure Mailpit automatically starts up whenever your VPS boots or recovers from a crash, create a systemd service file:

sudo nano /etc/systemd/system/mailpit.service

Paste the following configuration inside the file. This chains our database location, email limit thresholds, and authentication requirements together:

[Unit]
Description=Mailpit Email Testing Tool
After=network.target

[Service]
Type=simple
User=mailpit
Group=mailpit
ExecStart=/usr/local/bin/mailpit --listen localhost:8025 --database /var/lib/mailpit/mailpit.db --max 1000 --ui-auth-file /var/lib/mailpit/auth
Restart=always
RestartSec=5

# Optional security sandboxing
ProtectSystem=full
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Save and exit (Ctrl+O, Enter, then Ctrl+X). Now, activate and launch the service:

# Reload systemd to recognize the new configuration
sudo systemctl daemon-reload

# Enable the service to run on boot
sudo systemctl enable mailpit

# Start Mailpit immediately
sudo systemctl start mailpit

# Verify that it is running correctly without errors
sudo systemctl status mailpit

Note: Mailpit uses SQLite's WAL (Write-Ahead Log) mode. When emails arrive, data is instantly saved to mailpit.db-wal first. The main mailpit.db file size will update periodically or whenever the service gracefully restarts.

Configure Nginx Reverse Proxy with SSL

To access your dashboard securely via HTTPS, set up a server block routing traffic from your subdomain to Mailpit's internal port (8025). Mailpit relies on WebSockets for real-time dashboard updates, so ensure your configuration includes the HTTP Upgrade headers.

Create or update your Nginx configuration:

server {
    server_name mailpit.example.com;

    location / {
        proxy_pass http://localhost:8025;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Authorization $http_authorization;
        proxy_pass_header Authorization;

        # WebSocket support for real-time UI updates
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }

    listen [::]:443 ssl;
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
}

Test your configuration syntax and apply the changes:

sudo nginx -t
sudo systemctl restart nginx

Firewall Rules Reference

If you use a cloud provider or external managed firewall (like Hostinger's Firewall Dashboard), you must ensure your ports match your application architecture:

• Web Dashboard Access: You do not need to open port 8025 to the public internet. External users visit your site over standard HTTP/HTTPS ports, which Nginx handles internally. Ensure your firewall accepts incoming traffic on Port 80 and Port 443.
• App Email Routing (Port 1025):
  • If your websites/applications sending the emails are hosted on this exact same VPS, you do not need to alter your firewall. Localhost traffic is processed internally.
  • If you are sending emails to Mailpit from external servers or your local computer, add a firewall Accept rule for TCP Port 1025. Tip: Set the Source field to your external server's specific IP address rather than "Any" to prevent unauthorized public access.