add documentation for 1.0.0

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

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 <your-instance>/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@<your-domains.tld>, 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.

examples/config.yaml

@@ -1,8 +1,20 @@
 ---
-api_endpoint: https://mailcow.example.com
+# Base-Url of your Mailcow instance.
-api_key: aaaaa-bbbbb-ccccc-ddddd-eeeee
+# format: "https://mail.example.com"
-admin_email: admin@example.com
+api_endpoint: 
 
+# Read/Write API Key from your Mailcow instance
+# See the [+] API Section at <your-instance>/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@<your-domains.tld>, one entry should be - security
 mail_prefixes:
   - abuse
   - admin