stpaquet/alpinemailcatcher repository overview

⁠Docker Alpine MailCatcher

MailCatcher NG on the latest Alpine Linux. Catch every email your application sends, and read them in a web UI, without delivering anything to real recipients.

• SMTP server on port 1025
• Web interface on port 1080
• Small image, built on Alpine Linux

⁠Quick start

docker run -d --name mailcatcher -p 1080:1080 -p 1025:1025 stpaquet/alpinemailcatcher

1. Point your application's SMTP settings at localhost:1025.
2. Open http://localhost:1080⁠ to read the captured messages.

On Docker Machine setups (Windows or older Mac), use the Docker Machine IP instead of localhost.

⁠Configuration

Set these with -e on docker run or in a docker-compose.yml file.

Example: keep up to 60 messages.

docker run -d --name mailcatcher -p 1080:1080 -p 1025:1025 -e MAIL_LIMIT=60 stpaquet/alpinemailcatcher

⁠Changing ports

The ports inside the container are fixed. Change the host side of the mapping instead. This example exposes the web UI on 3080 and SMTP on 3025:

docker run -d --name mailcatcher -p 3080:1080 -p 3025:1025 stpaquet/alpinemailcatcher

⁠Docker Compose

services:
  mailcatcher:
    image: stpaquet/alpinemailcatcher:latest
    container_name: mailcatcher
    restart: on-failure:10
    environment:
      - MAIL_LIMIT=70
      - TIMEZONE=America/Los_Angeles
    ports:
      - "1080:1080"
      - "1025:1025"

⁠Message persistence

By default messages live in memory and are lost when the container stops. To store them in SQLite, mount a volume on the MailCatcher home directory and start MailCatcher with --persistence:

docker run -d --name mailcatcher \
  -p 1080:1080 -p 1025:1025 \
  -v mailcatcher-data:/home/mailcatcher/.mailcatcher \
  stpaquet/alpinemailcatcher \
  sh -c "mailcatcher --foreground --smtp-port=1025 --http-port=1080 --ip=0.0.0.0 --messages-limit=50 --persistence"

The database is stored at /home/mailcatcher/.mailcatcher/mailcatcher.db inside the container.

With Docker Compose:

services:
  mailcatcher:
    image: stpaquet/alpinemailcatcher:latest
    ports:
      - "1080:1080"
      - "1025:1025"
    volumes:
      - mailcatcher-data:/home/mailcatcher/.mailcatcher
    command: sh -c "mailcatcher --foreground --smtp-port=1025 --http-port=1080 --ip=0.0.0.0 --messages-limit=$$MAIL_LIMIT --persistence"

volumes:
  mailcatcher-data:

⁠Pulling and upgrading

docker pull stpaquet/alpinemailcatcher:latest

If docker pull fails with unauthorized: please use personal access token, your Docker Hub account uses 2FA. Create a Docker Hub access token⁠, then run docker login --username <username> and use the token as the password.

⁠Versions

Ruby and SQLite versions can change when the image is rebuilt. To list every installed package in a running container:

docker exec -i mailcatcher apk info -vv | sort

⁠Supported architectures

• linux/amd64 (x86_64)
• linux/arm64 (Apple Silicon, ARM servers)
• linux/386 (x86_32)
• linux/arm/v7 and linux/arm/v6

Need another architecture? Update the Dockerfile⁠ and open a pull request.

⁠Documentation and links

• Usage guide⁠: install, run, persistence, and configuration in more detail
• Changelog⁠: every release and what changed
• Beginner guide (Medium)⁠: MailCatcher with Docker and Docker Compose
• MailCatcher NG⁠: the MailCatcher fork this image packages (website⁠)

⁠License

Released under the MIT License⁠.