From 1204730924436ef9e1c7c49c9557837f9a5ed0e8 Mon Sep 17 00:00:00 2001 From: clarkzjw Date: Wed, 8 Feb 2023 00:40:09 -0800 Subject: fork https://github.com/mattsta/mailweb --- ansible/README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 2 deletions(-) (limited to 'ansible/README.md') diff --git a/ansible/README.md b/ansible/README.md index f26ed5a..7b2591b 100644 --- a/ansible/README.md +++ b/ansible/README.md @@ -1,3 +1,66 @@ -# mail +mailweb: Matt's Mail and Web Ansible Config +=========================================== -Self hosted mail server +## What Is It? + +This is an Ansible playbook containing Ansible roles to configure +my personal mail infrastructure components including: + +- postfix +- dovecot +- rspamd +- borg-backup +- fail2ban + +Also includes web components for installing multi-site `nginx` servers. + +`mailweb` was created to apply on modern Ubuntu servers with a current +release version of Bionic 18.04 LTS (meaning: packages are deployed using +the `apt` module only currently). + +A full writeup about this architecutre is at [Building a Production Mail Server in 2018](https://matt.sh/email2018) + +## Organization + +To avoid mistakes like accidentally publishing all your private keys or +backup passphrases, we take advantage of Ansible's directory search hierarchy +to isolate non-public content from role directories. + +For example: to avoid committing our private keys to the public repository, +instead of putting keys in a subdirectory of the role itself (e.g. `./roles/certs/files/tls/site-key.pem`), +we place them at the top level `file` path Ansible also searches (e.g. `./files/certs/tls/site-key.pem`). + +The same goes for `hosts_vars` and `group_vars` using this insight from the +[Ansible docs](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#splitting-out-host-and-group-specific-data): + +> Tip: The `group_vars/` and `host_vars/` directories can exist in the playbook directory OR the inventory directory. If both paths exist, variables in the playbook directory will override variables set in the inventory directory. + +So, we place our sample vars in `inventory/{group,host}_vars` for publishing in this +repository, then for actual usage we write production vars at the top level (which overrides the `inventory/*` vars). + +Now all we have to do is _not_ commit top level `files`, `group_vars`, and `host_vars` directories +into the public repository (only commit on local internal branches). This is helped +by our `.gitignore` in the public branch. View comments in `.gitignore` for more details +about private usage. + + +## Contributing + +Contributions welcome! Any PRs about improving configs towards security, usability, performance, and cross platform growth is encouraged. + +If you want to make changes for your own needs (but maybe not for _everybody's_ needs), feel free to submit the changes and just guard them with enable `when` blocks activated by config variables. + +Hopefully we can keep this architecture alive as its package components and underlying distributions grow over time. + +### Potential Problems + +- Not extensively tested outside my personal environment + - there's probably default vars missing in places; feel free to submit fixes + +### Acceptable Improvements + +- Feel free to submit better cross-platform integration + - cross-OS package management (`if centos` vs. `if debian` etc) + - should include better version checking/version pinning so we don't try to load 2018 configs into older servers not supporting modern options + - cross-OS config file locations, handlers, etc +- Update config files when [newer standards or features](https://matt.sh/web2018) get implemented and released -- cgit v1.2.3