Guide to Installing Mailpit on Amazon Linux 2023 and Configuring for Laravel

· 3 min read
#laravel #mailpit #devops #aws #linux

Mailpit is an excellent email testing tool for developers, considered a modern successor to MailHog (which is no longer actively maintained). Mailpit is faster, more lightweight, and written in Go.

This article will guide you through installing Mailpit on Amazon Linux 2023, configuring Nginx as a reverse proxy, and connecting it to a Laravel application.

1. Installing Mailpit

First, download and install the latest Mailpit binary.

sudo curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh | bash

This command automatically downloads the binary and places it in /usr/local/bin/mailpit.

Next, we'll create a dedicated system user for Mailpit to ensure security:

sudo useradd -r -s /usr/sbin/nologin mailpit

Verify the binary path to be sure:

which mailpit
# Output usually is: /usr/local/bin/mailpit

2. Configure Systemd Service

To run Mailpit in the background and start automatically with the system, create a systemd service file.

Create file /etc/systemd/system/mailpit.service:

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

Paste the following content:

[Unit]
Description=Mailpit
After=network.target

[Service]
User=mailpit
# MP_UI_AUTH_FILE=/etc/mailpit/authfile # If you want to use authentication here
ExecStart=/usr/local/bin/mailpit
Restart=always

[Install]
WantedBy=multi-user.target

Save and exit. Then reload the daemon and start Mailpit:

sudo systemctl daemon-reload
sudo systemctl enable mailpit
sudo systemctl start mailpit

Check the status:

sudo systemctl status mailpit

By default, Mailpit listens for SMTP on port 1025 and the Web UI on port 8025.

3. Configure Nginx Reverse Proxy (Optional)

If you want to access the Web UI via a domain or subdomain (e.g., mail.example.com) instead of opening port 8025 (which is safer), configure Nginx.

Create a new Nginx configuration file:

sudo nano /etc/nginx/conf.d/mailpit.conf

Sample content:

server {
    listen 80;
    server_name mail.example.com; # Replace with your domain

    location / {
        proxy_pass http://127.0.0.1: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;
        
        # Configuration for WebSocket (Mailpit uses WebSocket for live updates)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Check syntax and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Since the Web UI contains test email content (potentially sensitive), you should password protect it.

  1. Install httpd-tools to get the htpasswd command (if not already installed): 
    sudo dnf install httpd-tools -y
  2. Create a password file: 
    sudo htpasswd -c /etc/nginx/.mailpit_htpasswd admin
  3. Update Nginx configuration: 
    location / {
    auth_basic "Restricted Area";
    auth_basic_user_file /etc/nginx/.mailpit_htpasswd;
    # ... other proxy configurations remain the same
}

4. Configure Laravel

Finally, configure your Laravel application to send emails through Mailpit. Open your project's .env file:

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

If your Laravel application is on a different server than Mailpit, replace MAIL_HOST with the IP of the server where Mailpit is installed and ensure port 1025 is open in the Security Group (AWS). However, a common pattern is to install Mailpit on the same dev/staging server.

5. Verification

  1. Use tinker to send a test email: 
    php artisan tinker

    Mail::raw('Mailpit test on Amazon Linux 2023!', function($msg) { $msg->to('test@example.com')->subject('Test Mailpit'); });
  2. Access the Web UI (via port 8025 or the configured Nginx domain) to view the email just sent.

And that's it! you now have a robust and secure email catching system for development.

Comments