Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ansibleguy/sw_mailcow

Ansible role to deploy mailcow on a linux server
https://github.com/ansibleguy/sw_mailcow

ansible ansible-role docker-container iac infrastructure-as-code mailcow mailcow-dockerized mailing mailserver webmail

Last synced: about 1 month ago
JSON representation

Ansible role to deploy mailcow on a linux server

Host: GitHub
URL: https://github.com/ansibleguy/sw_mailcow
Owner: ansibleguy
License: other
Created: 2022-08-14T13:37:09.000Z (over 2 years ago)
Default Branch: latest
Last Pushed: 2024-11-10T10:49:40.000Z (3 months ago)
Last Synced: 2024-11-10T11:30:28.788Z (3 months ago)
Topics: ansible, ansible-role, docker-container, iac, infrastructure-as-code, mailcow, mailcow-dockerized, mailing, mailserver, webmail
Language: Jinja
Homepage:
Size: 84 KB
Stars: 4
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt

Awesome Lists containing this project

README

# Ansible Role - MailCow

Role to deploy [MailCow dockerized](https://github.com/mailcow/mailcow-dockerized) on a linux server.

This role follows the official [installation instructions](https://mailcow.github.io/mailcow-dockerized-docs/de/i_u_m/i_u_m_install/).

[![Molecule Test Status](https://badges.ansibleguy.net/sw_mailcow.molecule.svg)](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/molecule.sh.j2)
[![YamlLint Test Status](https://badges.ansibleguy.net/sw_mailcow.yamllint.svg)](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/yamllint.sh.j2)
[![PyLint Test Status](https://badges.ansibleguy.net/sw_mailcow.pylint.svg)](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/pylint.sh.j2)
[![Ansible-Lint Test Status](https://badges.ansibleguy.net/sw_mailcow.ansiblelint.svg)](https://github.com/ansibleguy/_meta_cicd/blob/latest/templates/usr/local/bin/cicd/ansiblelint.sh.j2)
[![Ansible Galaxy](https://badges.ansibleguy.net/galaxy.badge.svg)](https://galaxy.ansible.com/ui/standalone/roles/ansibleguy/sw_mailcow)

Molecule Logs: [Short](https://badges.ansibleguy.net/log/molecule_sw_mailcow_test_short.log), [Full](https://badges.ansibleguy.net/log/molecule_sw_mailcow_test.log)

**Tested:**
* Debian 11

----

## Install

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

# from galaxy
ansible-galaxy install ansibleguy.sw_mailcow

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

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

----

## Prerequisites

See: [Prerequisites](https://github.com/ansibleguy/sw_mailcow/blob/stable/Prerequisites.md)

----

## Advertisement

* Need **professional support** using Ansible or MailCow? Contact us:

E-Mail: [[email protected]](mailto:[email protected])

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
mailcow:
fqdn: 'srv.template.ansibleguy.net'
# per example: 'srv.template.ansibleguy.net' must be a valid, public dns-hostname of the server

# if you don't have IPv6
ipv6: false

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

config: # add config overrides for 'mailcow.conf'
WEBAUTHN_ONLY_TRUSTED_VENDORS: 'y'

auto_update:
enable: true # enable auto-updates

backup:
retention_days: 60 # default = 14
```

Bare minimum example:
```yaml
mailcow:
fqdn: 'srv.template.ansibleguy.net'
```

If you want to use the built-in (_not ansible-managed_) webserver:
```yaml
mailcow:
fqdn: 'srv.template.ansibleguy.net'
# per example: 'srv.template.ansibleguy.net' must be a valid, public dns-hostname of the server

manage:
webserver: false

config:
HTTP_PORT: 80
HTTPS_PORT: 443
# if you want to use the built-in letsencrypt support
SKIP_LETS_ENCRYPT: 'n'
ACME_CONTACT: '[email protected]'
ADDITIONAL_SAN: 'smtp.template.ansibleguy.net,mail.*'
```

### Execution

Run the playbook:
```bash
ansible-playbook -K -D -i inventory/hosts.yml playbook.yml
```

There are also some useful **tags** available:
* docker
* webserver

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_)

* **Configuration**
* Service to start containers on boot: 'mailcow.service'

* **Default config**:
* Directories:
* Base: '/var/lib/mailcow'
* Data: '/var/lib/docker/volumes' (_cannot be changed by role_)
* Backup: '/var/backups/mailcow'

* **Default opt-ins**:
* Docker => using [THIS Role](https://github.com/ansibleguy/infra_docker_minimal)
* Dependencies
* Server
* Docker-compose
* Nginx proxy on docker-host => using [THIS Role](https://github.com/ansibleguy/infra_nginx)

* Features:
* [SOGo Groupware](https://www.sogo.nu/)
* Apache Solr
* ClamAV (_virus scanner_)

* IPv6 enabled
* Daily backup using the [backup script](https://mailcow.github.io/mailcow-dockerized-docs/backup_restore/b_n_r-backup/)

* **Default opt-outs**:
* Auto update using the [update script](https://mailcow.github.io/mailcow-dockerized-docs/i_u_m/i_u_m_update/)

----

## Info

* **Info:** Consider using a **Mail Gateway to gain Security**!

Per example: [Proxmox Mail Gateway](https://github.com/ansibleguy/sw_proxmox_mail_gw)

* **Info:** Check out the troubleshooting information: [Troubleshooting](https://github.com/ansibleguy/sw_mailcow/blob/stable/Troubleshooting.md)

* **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_mailcow/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!

* **Info:** Default credentials:

User: admin

Password: moohoo

* **Info:** For more detailed information - look into the [nice documentation](https://mailcow.github.io/mailcow-dockerized-docs) provided by MailCow!

* **Info:** If the setup fails after creating the config - you need to remove the config file (_/var/lib/mailcow/mailcow.conf_) manually, so the role will know it isn't initialized already!

* **Warning:** The automatic **BACKUPS** are placed on the same system and need to be copied to a **REMOTE** location to be SAFE!

* **Warning:** Using **NFTables** on the MailCow host is **NOT RECOMMENDED** as IPTables rules are auto-managed by docker and the MailCow containers.

Containers may fail if the ruleset is not as expected.

You can disable the firewall check using the `ignore_firewall_check: true` setting.