From e7c7a6bf3025a88b89ac8786a2504147d668818b Mon Sep 17 00:00:00 2001 From: Adora Laura Kalb Date: Fri, 26 Jul 2024 10:57:39 +0200 Subject: [PATCH] add documentation for 1.0.0 --- CHANGELOG.md | 15 +++++++ README.md | 101 +++++++++++++++++++++++++++++++++++++++++++ examples/config.yaml | 18 ++++++-- 3 files changed, 131 insertions(+), 3 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 README.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..42bc3ee --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + + +## [Unreleased] + +## [1.0.0] - 2024-07-26 +First release of `mailcow-admin-aliases` + +[unreleased]: https://code.lila.network/adoralaura/mailcow-admin-aliases/compare/1.0.0...HEAD +[1.0.0]: https://code.lila.network/adoralaura/mailcow-admin-aliases/releases/tag/1.0.0 diff --git a/README.md b/README.md new file mode 100644 index 0000000..de23ddb --- /dev/null +++ b/README.md @@ -0,0 +1,101 @@ +# mailcow-admin-aliases +![status-badge](https://ci.lila.network/api/badges/24/status.svg) +[![Please don't upload to GitHub](https://nogithub.codeberg.page/badge.svg)](https://nogithub.codeberg.page) + +## Introduction +Many mail administrators (me included) want to have some specific email addresses (like postmaster@..., security@..., abuse@..., etc.) always point to a dedicated administrator mailbox, so that e.g. mails regarding abuse or security issues will always be at one central management point. + +If you are using [Mailcow](https://docs.mailcow.email/) as your mail server, you'd have to manually add those mail addresses as _aliases_ by hand. I'm also hosting my own Mailcow instance, and by now I have enough (sub)domains that manually adding aliases gets tedious _very quickly_. Thats why I created `mailcow-admin-aliases`. + +With `mailcow-admin-aliases` you can (automatically) create the mail aliases you want, e.g. if you configure a new domain. In the [examples](examples/) folder you can find _systemd_ service and timer files to automate the creation of your aliases. `mailcow-admin-aliases` will check which ones already exist and will skip those. + +This application is successfully tested with mailcow `2023-03` to `2024-06c`, but it should work with older versions too. + +## Quick Start + +Installation of the required Mailcow instance is way out of scope of this documentation. For detailed instructions regarding Mailcow, please visit [it's documentation](https://docs.mailcow.email/) + + +To quickly get started with `mailcow-admin-aliases`, just download the binary from [the mailcow-admin-aliases Release page](https://code.lila.network/adoralaura/mailcow-admin-aliases/releases)... + +... fill out the config file... +```shell +vi config.yaml +``` +```yaml +--- +# Base-Url of your Mailcow instance. +# format: "https://mail.example.com" +api_endpoint: + +# Read/Write API Key from your Mailcow instance +# See the [+] API Section at /admin +# format: "XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX" +api_key: + +# The mail address the aliases should point to +# Should be a mailbox on your Mailcow instance +# format: "admin-mail@your-domain.com" +admin_email: + +# Local part of your important aliases you want created +# Example: if you want security@, one entry should be - security +mail_prefixes: + - abuse + - admin + - postmaster + - security + - webadmin + - webmaster +``` + +... and run it! +```shell +mailcow-admin-aliases --config /path/to/config.yaml +``` + +## `mailcow-admin-aliases` CLI flags +when using `mailcow-admin-aliases`, you have the following CLI flag options: +``` + -c, --config string Path to config file (default: $WorkDir/config.yaml) + --debug Enable debug logging (beats --quiet) + -d, --dry-run Show what this application *would* do + -q, --quiet Disable logging + -v, --version Show version information + -h, --help Show this overview +``` + +You can also see the list of CLI options with `--help` + +## How it works + +`mailcow-admin-aliases` queries the API of the configured Mailcow instance to +- get the currently configured Mailcow domains +- get the list of currently configured aliases +- create missing aliases + +## Scaling +As this is a Go application, performance shsould generally be pretty good. **However**, I currently do not have access to a big Mailcow test instance. Should you run into scaling/performance issues, please don't hesitate to contact me! + +## Contributing + +I use my own [Forgejo Instance](https://code.lila.network) to manage issues and pull requests. + +* If you have a trivial fix or improvement, go ahead and create a pull request, + addressing (with `@...`) the maintainer of this repository (see + [MAINTAINERS.md](MAINTAINERS.md)) in the description of the pull request. + +* If you plan to do something more involved, first please [send me a mail]( mailto:dev@lauka.net?subject=%5Bmailcow-admin-aliases%5D). + +### What to contribute + +The best way to help without speaking a lot of Go would be to share your +configuration, alerts, dashboards, and recording rules. If you have something +that works and is not in the repository, please pay it forward and +share what works. + +## Changelog +You can find the Changelog here: [Changelog](https://code.lila.network/adoralaura/mailcow-admin-aliases/src/branch/main/CHANGELOG.md) + +## License +`mailcow-admin-aliases` is available under the MIT license. See the [LICENSE](https://code.lila.network/adoralaura/mailcow-admin-aliases/src/branch/main/LICENSE) file for more info. diff --git a/examples/config.yaml b/examples/config.yaml index e2aff6a..9bf3f1a 100644 --- a/examples/config.yaml +++ b/examples/config.yaml @@ -1,8 +1,20 @@ --- -api_endpoint: https://mailcow.example.com -api_key: aaaaa-bbbbb-ccccc-ddddd-eeeee -admin_email: admin@example.com +# Base-Url of your Mailcow instance. +# format: "https://mail.example.com" +api_endpoint: +# Read/Write API Key from your Mailcow instance +# See the [+] API Section at /admin +# format: "XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX" +api_key: + +# The mail address the aliases should point to +# Should be a mailbox on your Mailcow instance +# format: "admin-mail@your-domain.com" +admin_email: + +# Local part of your important aliases you want created +# Example: if you want security@, one entry should be - security mail_prefixes: - abuse - admin