ansibleguy / sw_proxmox_mail_gw

Role to install Proxmox Mail Gateway on a linux server

Ansible Role - Proxmox Mail Gateway

Role to deploy Proxmox Mail Gateway on a linux server.

Tested:

• Debian 11

Install

# latest
ansible-galaxy role install git+https://github.com/ansibleguy/sw_proxmox_mail_gw

# from galaxy
ansible-galaxy install ansibleguy.sw_proxmox_mail_gw

# or to custom role-path
ansible-galaxy install ansibleguy.sw_proxmox_mail_gw --roles-path ./roles

# install dependencies
ansible-galaxy install -r requirements.yml

Prerequisites

See: Prerequisites

Functionality

• Package installation

  • Ansible dependencies (minimal)
  • Systemd
  • Proxmox Mail Gateway
  • PMG dependencies
    • postgreSQL
    • Postfix

• Configuration

  • default postgreSQL installation

  • Default opt-ins:

    • Nginx => using THIS Role

  • Default opt-outs:

    • Enterprise apt-repository (subscription needed)

Info

• Warning: IF YOU ARE USING A DEDICATED VM FOR THIS SETUP:

  You should probably use the ISO installation process.

  It might be better supported!

• Note: this role currently only supports debian-based systems

• Note: Most of the role's functionality can be opted in or out.

  For all available options - see the default-config located in the main defaults-file!

• Warning: Not every setting/variable you provide will be checked for validity. Bad config might break the role!

• Warning: If you choose to install the nginx web server (default) and want to use the built-in ACME certificate management - you will have to configure 'nginx.plain_site' to 'false'.

  As this 'ACME standalone integration' needs the port 80 to be not in use!

• Note: Check out the nice documentation provided by Proxmox!

• Warning: Docker containers ARE NOT SUPPORTED.

• Info: PMG's web interface default login is done via PAM/System users.

  Normally, at first, via 'root'.

Usage

You want a simple Ansible GUI? Check-out my Ansible WebUI

Config

Define the config as needed:

pmg:
  fqdn: 'pmg.template.ansibleguy.net'  # valid, public dns-hostname of your server

  manage:
    webserver: true  # set to false to disable nginx-component

  nginx:  # configure the webserver settings => see: https://github.com/ansibleguy/infra_nginx
    aliases: ['mail-gw.ansibleguy.net']  # additional domains to add to the certificate
    ssl:
      mode: 'letsencrypt'  # or selfsigned/ca
      #  if you use 'selfsigned' or 'ca':
      #    cert:
      #      cn: 'Proxmox Mail Gateway'
      #      org: 'AnsibleGuy'
      #      email: '[email protected]'
    letsencrypt:
      email: '[email protected]'

Bare minimum example:

pmg:
  fqdn: 'pmg.template.ansibleguy.net'

Example to use PMG's built-in ACME:

pmg:
  fqdn: 'pmg.template.ansibleguy.net'

  nginx:
    aliases: ['mail-gw.ansibleguy.net']
    plain_site: false  # nginx will not bind to port 80
    letsencrypt:
      email: '[email protected]'

Example - if you want to setup postgreSQL manually:

pmg:
  fqdn: 'pmg.template.ansibleguy.net'

  manage:
    database: false

You might want to use 'ansible-vault' to encrypt your passwords:

ansible-vault encrypt_string

Execution

Run the playbook:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml

To debug errors - you can set the 'debug' variable at runtime:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e debug=yes