andrelohmann.mailpit

Mailpit

Overview

This role is used to install Mailpit and run it as a background service using systemd.

Requirements

This role works on Ubuntu.

Role Variables

The default settings for starting Mailpit are:

mailpit_smtp_port: 1025
mailpit_web_port: 8025
mailpit_release: latest

You can set additional variables to use Mailpit behind Apache:

mailpit_proxy_apache: true
mailpit_proxy_domain: _your.mailpit.domain_
mailpit_proxy_port: 80

Or behind Nginx:

mailpit_proxy_nginx: true
mailpit_proxy_domain: _your.mailpit.domain_
mailpit_proxy_port: 80

Example Playbook

- hosts: mailpit
  roles:
     - { role: andrelohmann.mailpit }

Role Development

Special Features

This repository includes tools for role development:

yamllint
ansible-lint
molecule test
GitHub actions
automatic version updates
update ansible-galaxy
show build status
testing in Vagrant (for development)
testing with Molecule (inside or outside Vagrant)
testing with Docker containers
developing in Visual Studio Code

Prerequisites

For more details, refer to this link: https://thedatabaseme.de/2022/01/17/automated-testing-your-ansible-role-with-molecule-and-github-actions/

You need:

VirtualBox + Vagrant (only if you plan to test with Vagrant)
Docker Desktop
Visual Studio Code + remote extension pack (dependencies are listed in .vscode/extensions.json)

Development Setup

This Ansible role is developed and tested using Molecule. It uses Visual Studio Code and a development container to manage all necessary tools (Ansible, linter, Molecule).

The role will be tested on two Ubuntu versions (Focal, Jammy).

To start the Molecule test containers from the development container, you need to mount the Docker socket into the development container.

Important Folders and Files

.devcontainer

Defines the Dockerfile for the development container
Configures how the development container starts (like mounting Docker socket)

molecule/default/Dockerfile.js

Used as a template for all platforms defined in molecule/default/molecule.yml
Sets up the environment to support systemd services (needed for certain Ansible roles)
Installs everything required to run Ansible in the container
Aligns with the platform attributes in molecule/default/molecule.yml
For more info, refer to the Molecule documentation

How to Use

Visual Studio Code

Go to the root directory of your role and start Visual Studio Code:

code .

From the development container, you can run these commands:

yamllint .
ansible-lint .
molecule create
molecule test

Vagrant + VirtualBox

Go to the root directory of your role.
Navigate to the Vagrant folder.
Start and access the Vagrant machine:

vagrant up
vagrant ssh

Go to the role folder:

cd /etc/ansible/roles/ansible-role-[tab]

Now you can run all tests:

yamllint .
ansible-lint .
molecule create
molecule test

Build and Release Process

The Ansible role includes GitHub workflows for testing and releasing.

Protect the Master/Main Branch

Go to Settings -> Branches -> Add branch protection rule
Set the branch name as main or master
Check "Require a pull request before merging"
Manage "Require approvals" according to your needs

Set GITHUB_TOKEN Permissions

Go to Settings -> Actions -> General -> Workflow permissions -> Set to read and write

Commit Messages

Commit messages should be in a specific format for version updates.

Patch

For version 0.0.x:

fix(single_word): description

Minor

For version 0.x.0:

feat(single_word): description

Major

For version x.0.0:

perf(single_word): description
BREAKING CHANGE: explanation of the breaking change

Ensure "BREAKING CHANGE: " is on the second line or later. If it's a single-line commit message, the major version update won't be recognized.

Add GALAXY_API_KEY Secret

Log in at https://galaxy.ansible.com/ with your GitHub account.
Get your Galaxy API key from Preferences -> API Key.
Go to your GitHub repository.
Navigate to Settings -> Secrets and Variables -> Actions -> New repository secret.
Use "GALAXY_API_KEY" as the key and paste your Galaxy API key as the value.