WIP doc

content/documentation/cookbook/service-manager.md

@@ -3,7 +3,8 @@ title = "Service Managers (eg. systemd)"
 weight = 40
 +++
 
-You may want to start Aerogramme on boot.
+You may want to start Aerogramme automatically on boot,
+restart it if it crashes, etc. Such actions can be achieved through a service manager.
 
 ## systemd
 
@@ -60,6 +61,15 @@ sudo aerogramme \
 sudo systemctl reload aerogramme
 ```
 
+## Other service managers
+
+Other service managers exists: SMF (illumos / solaris), OpenRC (alpine & co), rc (FreeBSD, OpenBSD, NetBSD).
+Feel free to open a PR to add some documentation.
+You would not use System V initialization scripts...
+
+
+
+<!--
 ## docker-compose
 
 An example docker compose deployment with Garage included:
@@ -84,3 +94,4 @@ services:
       - garage-meta:/var/lib/garage/meta
       - garage-data:/var/lib/garage/data
 ```
+-->

content/documentation/cookbook/smtp-server.md

@@ -3,4 +3,98 @@ title = "SMTP servers"
 weight = 50
 +++
 
-Todo
+Many email Message Transfer Agent (MTA) supports LMTP delivery.
+Some of them are covered here.
+
+## Postfix
+
+Configuring Postfix requires to add these 2 lines to `main.cf`:
+
+```ini
+virtual_mailbox_domains = your-domain.tld
+virtual_transport = lmtp:[::1]:1025
+```
+
+Make sure that `your-domain.org` is not already configured in the `mydomain` variable,
+or it might conflict with Postfix local delivery logic.
+
+*Indeed, Postfix internally has its default configuration for "local" mail delivery,
+that maps to the old way of managing emails. LMTP delivery is a more recent, and maps
+to the "virtual" mail delivery mechanisms of Postfix. Your goal is thus to deactivate
+as much as possible the "local" delivery capabilities of Postfix and only allow
+the "virtual" ones.*
+
+You can learn more about Postfix LMTP capabilities on this page: [lmtp(8)](https://www.postfix.org/lmtp.8.html).
+
+## OpenSMTPD
+
+Something like below might work (untested):
+
+```bash
+action "remote_mail" lmtp "/var/run/dovecot/lmtp" rcpt-to virtual <virtuals>
+match from any for domain "your-domain.tld" action "remote_mail"
+```
+
+The syntax is described in their manpage [smtpd.conf(5)](https://man.openbsd.org/smtpd.conf#lmtp).
+
+## Other servers
+
+[Maddy](https://maddy.email/) might be configured to deliver LMTP messages to Aerogramme through its [SMTP & LMTP transparent forwarding](https://maddy.email/reference/targets/smtp/#smtp-lmtp-transparent-forwarding) feature.
+
+[Exim](https://www.exim.org/) has some support [for LMTP](https://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_lmtp_transport.html) too.
+
+[sendmail](https://www.proofpoint.com/us/products/email-protection/open-source-email-solution) might deliver to LMTP through a dedicated binary named [smtpc](https://www.sympa.community/manual/customize/lmtp-delivery.html)
+
+<!--
+Let start by creating a folder for Postfix, for example `/opt/aerogramme-postfix`:
+
+```bash
+mkdir /tmp/aerogramme-postfix
+cd /opt/aerogramme-postfix
+mkdir queue
+```
+
+To run Postfix, you need some users / groups setup (do it in a container if you don't want to mess up your system):
+
+```bash
+sudo useradd postfix
+sudo groupadd postdrop
+```
+
+The considered `main.cf`:
+
+```
+mynetworks=127.0.0.0/8
+compatibility_level=3.6
+queue_directory=/tmp/postfix-test/queue
+data_directory=/tmp/postfix-test/data
+maillog_file=/dev/stdout
+alias_database=
+alias_maps=
+
+virtual_mailbox_domains=saint-ex.deuxfleurs.org
+virtual_transport=lmtp:[::1]:1025
+```
+
+The considered `master.cf`:
+
+```
+smtp inet n - n - - smtpd
+smtp unix - - n - - smtp
+lmtp unix - - n - - lmtp
+anvil unix - - n - 1 anvil
+rewrite unix - - n - - trivial-rewrite
+cleanup unix n - n - 0 cleanup
+qmgr fifo n - n 300 1 qmgr
+tlsmgr unix - - n 1000? 1 tlsmgr
+bounce unix - - n - 0 bounce
+defer unix - - n - 0 bounce
+trace unix - - n - 0 bounce
+error unix - - n - - error
+retry unix - - n - - error
+discard unix - - n - - discard
+virtual unix - n n - - virtual
+proxymap unix - - n - - proxymap
+postlog unix-dgram n - n - 1 postlogd
+```
+-->

content/documentation/cookbook/tls-encryption.md

@@ -41,13 +41,24 @@ This example will be given for Let's Encrypt with Lego for a DNS01 challenge wit
 ```bash
 GANDIV5_API_KEY=xxx \
 GANDIV5_PERSONAL_ACCESS_TOKEN=xxx \
-lego --email you@example.tld --dns gandiv5 --domains imap.example.tld --domains smtp.example.tld run
+lego \
+  --email you@example.tld \
+  --dns gandiv5 \
+  --domain example.tld \
+  --domains imap.example.tld \
+  --domains smtp.example.tld \
+  run
 ```
 
-*Note: theoretically only `GANDIV5_PERSONAL_ACCESS_TOKEN` should be required, but it did not work for me.*
+*Note 1: theoretically only `GANDIV5_PERSONAL_ACCESS_TOKEN` should be required, but it did not work for me.*
+
+*Note 2: we generate a certificate for the root domain and SMTP because it will simplify your testing while following the cookbook.
+But if you already have a working email stack, it's not required.*
+
 
 If the command ran successfully, you now have 2 files:
- - `.lego/certificates/imap.example.tld.crt`
+ - `.lego/certificates/example.tld.crt`
- - `.lego/certificates/imap.example.tld.key`
+ - `.lego/certificates/example.tld.key`
 
 You can directly use them in Aerogramme (the first one must be put on `certs` and the second one on `key`).
+You must configure some way to automatically renew your certificates, the [lego documentation](https://go-acme.github.io/lego/usage/cli/renew-a-certificate/) explains how you can do it.