https://github.com/ansibleguy/sw_proxmox_mail_gw
Role to install Proxmox Mail Gateway on a linux server
https://github.com/ansibleguy/sw_proxmox_mail_gw
ansible ansible-role anti-spam anti-spoofing iac infrastructure-as-code mailing proxmox proxmox-mail-gateway security
Last synced: about 2 months ago
JSON representation
Role to install Proxmox Mail Gateway on a linux server
- Host: GitHub
- URL: https://github.com/ansibleguy/sw_proxmox_mail_gw
- Owner: ansibleguy
- License: other
- Created: 2022-08-14T09:12:59.000Z (about 3 years ago)
- Default Branch: latest
- Last Pushed: 2024-08-05T19:54:10.000Z (about 1 year ago)
- Last Synced: 2024-08-05T23:08:04.029Z (about 1 year ago)
- Topics: ansible, ansible-role, anti-spam, anti-spoofing, iac, infrastructure-as-code, mailing, proxmox, proxmox-mail-gateway, security
- Language: Python
- Homepage:
- Size: 90.8 KB
- Stars: 9
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://www.proxmox.com/en/proxmox-mail-gateway)
# Ansible Role - Proxmox Mail Gateway
Role to deploy [Proxmox Mail Gateway](https://www.proxmox.com/en/proxmox-mail-gateway) on a linux server.
[](https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html)
[](https://github.com/ansibleguy/sw_proxmox_mail_gw/actions/workflows/lint.yml)
[](https://galaxy.ansible.com/ui/standalone/roles/ansibleguy/sw_proxmox_mail_gw)
**Molecule Integration-Tests**:
* Status: [](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/molecule.sh.j2) |
[](https://github.com/ansibleguy/sw_proxmox_mail_gw/actions/workflows/integration_test_result.yml)
* Logs: [API](https://ci.ansibleguy.net/api/job/ansible-test-molecule-sw_proxmox_mail_gw/logs?token=2b7bba30-9a37-4b57-be8a-99e23016ce70&lines=1000) | [Short](https://badges.ansibleguy.net/log/molecule_sw_proxmox_mail_gw_test_short.log) | [Full](https://badges.ansibleguy.net/log/molecule_sw_proxmox_mail_gw_test.log)
Internal CI: [Tester Role](https://github.com/ansibleguy/_meta_cicd) | [Jobs API](https://github.com/O-X-L/github-self-hosted-jobs-systemd)
**Tested:**
* Debian 11
* Debian 12
----
## Install
```bash
# 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](https://github.com/ansibleguy/sw_proxmox_mail_gw/blob/stable/Prerequisites.md)
----
## Advertisement
* Need **professional support** using Ansible or Proxmox Mail-Gateway? Contact us:
E-Mail: [contact@oxl.at](mailto:contact@oxl.at)
Tel: [+43 3115 40 900 0](tel:+433115409000)
Web: [EN](https://www.o-x-l.com) | [DE](https://www.oxl.at)
Language: German or English
* You want a simple **Ansible GUI**?
Check-out this [Ansible WebUI](https://github.com/ansibleguy/webui)
----
## Usage
### Config
Define the config as needed:
```yaml
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: 'pmg@template.ansibleguy.net'
letsencrypt:
email: 'pmg@template.ansibleguy.net'
```
Bare minimum example:
```yaml
pmg:
fqdn: 'pmg.template.ansibleguy.net'
```
Example to use PMG's built-in ACME:
```yaml
pmg:
fqdn: 'pmg.template.ansibleguy.net'
nginx:
aliases: ['mail-gw.ansibleguy.net']
plain_site: false # nginx will not bind to port 80
letsencrypt:
email: 'pmg@template.ansibleguy.net'
```
Example - if you want to setup postgreSQL manually:
```yaml
pmg:
fqdn: 'pmg.template.ansibleguy.net'
manage:
database: false
```
You might want to use 'ansible-vault' to encrypt your passwords:
```bash
ansible-vault encrypt_string
```
### Execution
Run the playbook:
```bash
ansible-playbook -K -D -i inventory/hosts.yml playbook.yml
```
To debug errors - you can set the 'debug' variable at runtime:
```bash
ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e debug=yes
```
----
## 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](https://github.com/ansibleguy/infra_nginx)
* **Default opt-outs**:
* Enterprise apt-repository (_[subscription needed](https://www.proxmox.com/en/proxmox-mail-gateway/pricing)_)
----
## Info
* **Warning:** **IF YOU ARE USING A DEDICATED VM FOR THIS SETUP**:
You should probably use the [ISO installation process](https://www.proxmox.com/en/downloads/category/proxmox-mail-gateway).
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](https://github.com/ansibleguy/sw_proxmox_mail_gw/blob/latest/defaults/main/1_main.yml)!
* **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](https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#sysadmin_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](https://pmg.proxmox.com/pmg-docs/pmg-admin-guide.html#_features) 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'.