Forge Home


Install & Configure MailHog


2,239 latest version

3.1 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.1.5 (latest)
  • 1.1.4
released Jan 18th 2021
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.0 < 8.0.0
  • Ubuntu

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'veepshosting-mailhog', '1.1.5'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add veepshosting-mailhog
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install veepshosting-mailhog --version 1.1.5

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



veepshosting/mailhog — version 1.1.5 Jan 18th 2021

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with mailhog
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module


This module lets you use Puppet to install and configure MailHog

Module Description

MailHog is an email testing tool for developers written by Ian Kent ( It receives mail and displays it in a WebUI. No login required, no need for user accounts. Just all received mail is shown in the WebUI.

You can access the WebUI by opening http://$::ipaddress:8025 (default port, feel free to change) in your browser.

MailHog will receive mail (default is smtp on port 1025) and will display it in the WebUI. You can view and delete the mail. If required one could also forward the mail to the corresponding external Mailserver for the receipients e-mail domain.

The configuration is straight forward - take a look at the params.pp class for default values.

Due to the size limitation on puppet forge the module will download the mailhog binary to the target system.


What mailhog affects

  • Deploys mailhog binary depending on the architecture the local machine uses (amd64, arm or x86).
  • Creates a "mailhog" user
  • Deploys a mailhog.conf file with the available config values
  • Installs "daemon" package
  • Deploys a initd script to start/stop mailhog as a daemon

Setup Requirements

This mailhog module requires:

Beginning with mailhog

The simplest way to get MailHog up and running with the mailhog module is to just add the mailhog-class to your manifest:

include mailhog

That's it! Really. Didn't hurt, did it? ;-)

You want to change the ip & port MailHog receives incoming mails? No problem:

class { 'mailhog':
  smtp_bind_addr_ip   => "",
  smtp_bind_addr_port => "1125"

include mailhog


Put the classes, types, and resources for customizing, configuring, and doing the fancy stuff with your module here.



Public Classes

  • mailhog: Main class, includes all other classes

Private Classes

  • mailhog::params: Holds default values for MailHog & module config
  • mailhog::install: Handles deployment of user, dependencies and mailhog binary
  • mailhog::config: Handles deployment of mailhog config file
  • mailhog::service: Handles deployment of the init.d script

Download binary

Due to the size limit of packages uploaded to the Forge, the module was designed to offer two options on where to source the MailHog binary from:

  • $download_mailhog = true (default): The MailHog binary will be downloaded from the official MailHog Github repository. This is good for a few servers as this is very modular and the module can be used right away.
  • $download_mailhog = false: The MailHog binary will be sourced from the "files" subdirectory of this module. This is perfect to roll out multiple hosts with this module. In case this feature is required, the admin needs to download the 3 MailHog Linux binaries (MailHog_linux_386, MailHog_linux_arm, MailHog_linux_amd64) to the "files" folder of this module. Just call the mailhog class with $download_mailhog = false.

###Parameters The following parameters are available in the ::mailhog class:

####MailHog config values | parameter | default value | description | |------------------------------------------|-------------------------|--------------| | $api_bind_ip | | The IP address the API server will be bound to. | | $api_bind_port | 8025 | The port the API server will be bound to. | | $api_bind_host | undef | API URL for MailHog UI to connect to, e.g. if API and WebUI are deployed on different hosts/IPs. | | $cors_origin | undef | CORS Access-Control-Allow-Origin header for API endpoints. | | $hostname | $::fqdn | Hostname to use for EHLO/HELO and message IDs. | | $invite_jim | false | Decide whether to invite Jim, the chaos monkey. Jim is the MailHog Chaos Monkey, inspired by Netflix. He will:Reject connectionsRate limit connectionsReject authenticationReject sendersReject recipients| | $jim_accept | 0.99 | Chance of accepting an incoming connection (1.0 = 100%) | | $jim_disconnect | 0.005 | Chance of a disconnect | | $jim_linkspeed_affect | 0.1 | Chance of the link speed being affected for an incoming mail | | $jim_linkspeed_max | 10240 | Maximum link speed (in bytes per second) | | $jim_linkspeed_min | 1024 | Minimum link speed (in bytes per second) | | $jim_reject_auth | 0.05 | Chance of rejecting authentication (AUTH) | | $jim_reject_recipient | 0.05 | Chance of rejecting a recipient (RCPT TO) | | $jim_reject_sender | 0.05 | Chance of rejecting a sender (MAIL FROM) | | $mongo_coll | messages | MongoDB collection if MongoDB is being used as backend storage | | $mongo_db | mailhog | MongoDB database if MongoDB is being used as backend storage | | $mongo_uri_ip | | MongoDB URI IP if MongoDB is being used as backend storage | | $mongo_uri_port | 27017 | MongoDB URI port if MongoDB is being used as backend storage | | $outgoing_smtp | undef | JSON file containing outgoing SMTP servers | | $smtp_bind_addr_ip | | SMTP bind interface, this is where MailHog will receive incoming mails | | $smtp_bind_addr_port | 1025 | SMTP bind port, this is where MailHog will receive incoming mails | | $storage | memory | Message storage: memory or mongodb | | $ui_bind_addr_ip | | HTTP bind interface for WebUI | | $ui_bind_addr_port | 8025 | HTTP bind port for WebUI |

####Puppet module config values | parameter | default value | description | |------------------------------------------|--------------------------|--------------| | $mailhog_version | 0.2.0 | Version of Mailhog to be used. Feel free to look up the latest release version from GitHub | | $config | /etc/mailhog.conf | Path and filename for mailhog config file at the target system | | $mailhog::service_manage | true | Whether the service should be managed by this module or not. | | $service_enable | true | Whether the service should be started on boot or not. | | $service_ensure | running | Either "running" or "stopped" | | $service_name | mailhog | Name of the service | | $binary_path | /usr/bin | Where to place the mailhog binary at the target system | | $user | mailhog | Username of the user running mailhog service at the target system. | | $homedir | /var/lib/mailhog | Home directory of above mailhog user. | | $download_mailhog | true | Enable/Disable wget download of MailHog binary. |


Today the module was tested with Ubuntu 14.04 and 12.04 only. It might work with other Linux versions though. The more time I have the more I will test. Any help would be really appreciated.


Feel free to pull the repository and commit changes. I will review them asap and add them if I think they are helpful or reasonable. No guarantees but a lot of heart ;-)


To see who's already involved, see the [list of contributors.]