From 5e46655b9fa96e1af9edcac15cb483ed0048c65f Mon Sep 17 00:00:00 2001
From: Daniel Lerch <36048059+daniel-lerch@users.noreply.github.com>
Date: Tue, 17 Oct 2023 13:15:30 +0200
Subject: [PATCH] Explan how to setup email delivery and relay

---
 README.md               | 46 ++++++++++++++++++++++++++++++++++++++++-
 docs/docker-compose.yml | 19 +++++++++++++++++
 2 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d4343df..25cae57 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Korga
 
-![Ubuntu build and tests](https://github.com/daniel-lerch/korga/workflows/Ubuntu%20build%20and%20tests/badge.svg)
+[![Build and tests](https://github.com/daniel-lerch/korga/actions/workflows/main.yml/badge.svg)](https://github.com/daniel-lerch/korga/actions/workflows/main.yml)
 [![](https://img.shields.io/docker/pulls/daniellerch/korga.svg)](https://hub.docker.com/r/daniellerch/korga)
 [![](https://img.shields.io/docker/image-size/daniellerch/korga/latest.svg)](https://hub.docker.com/r/daniellerch/korga)
 
@@ -108,6 +108,50 @@ This should be a 256 chars long alphanumeric text without special chars.
 
 Do not forget to recreate your container to take these changes into effect.
 
+### Email delivery
+
+Email delivery via SMTP can be configured with environment variables in `docker-compose.yml`:
+
+- `EmailDelivery__Enable`  
+Set this to `true` to enable Korga to send emails via SMTP
+- `EmailDelivery__SenderName`  
+The display name for system messages. Defaults to `Korga`
+- `EmailDelivery__SenderAddress`  
+The address Korga will send emails from. Usually this should be the email address for the credentials below.
+- `EmailDelivery__SmtpHost`  
+Defaults to `smtp.strato.de`
+- `EmailDelivery__SmtpPort`  
+Defaults to `465`
+- `EmailDelivery__SmtpUseSsl`  
+Defaults to `true`
+- `EmailDelivery__SmtpUsername`
+- `EmailDelivery__SmtpPassword`
+
+### Email relay
+
+Korga's email relay requires a catchall IMAP inbox.
+Such an inbox receives all emails sent to a domain where no matching inbox was found, i.e. `*@example.org`.
+It can be configured with environment variables in `docker-compose.yml`:
+
+- `EmailRelay__Enable`  
+Set this to `true` to let Korga periodically check for emails to forward them. If `EmailDelivery__Enable` is set to `false`, this option will have no effect. Email relay depends on email delivery.
+- `EmailRelay__ImapHost`  
+Defaults to `imap.strato.de`
+- `EmailRelay__ImapPort`  
+Defaults to `993`
+- `EmailRelay__ImapUseSsl`  
+Defaults to `true`
+- `EmailRelay__ImapUsername`
+- `EmailRelay__ImapPassword`
+- `EmailRelay__RetrievalIntervalInMinutes`  
+Defaults to `2.0` (2 minutes)
+- `EmailRelay__ImapRetentionIntervalInDays`  
+Defaults to `1.0` (24 hours)
+- `EmailRelay__MaxHeaderSizeInKilobytes`  
+Defaults to `64` (64 KiB)
+- `EmailRelay__MaxBodySizeInKilobytes`  
+Defaults to `12288` (12 MiB). You must adjust MariaDB's `max_packet_size` if you want to increase this limit.
+
 ## Contributing
 
 Contributions are highly welcome. Please open an issue before implementing a feature to discuss your plans.
diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml
index f3d03f7..66bbbc8 100644
--- a/docs/docker-compose.yml
+++ b/docs/docker-compose.yml
@@ -14,11 +14,30 @@ services:
       # Uncomment below if you want to use Korga behind a reverse proxy like NGINX
       #- Hosting__AllowProxies=true
 
+      # Uncomment the three options below to login with OpenID Connect
+      # See the main README for instructions how to create client for Korga in your OpenID Connect Provider
+      #- OpenIdConnect__Authority=https://keycloak.example.org/realms/churchtools
+      #- OpenIdConnect__ClientId=korga
+      #- OpenIdConnect__ClientSecret=zX8bZkty9sGeUixRHgooMR6owhBzgQuP
+
       # Uncomment the three options below to sync with ChurchTools
       # See the main README for instructions on how to get a login token and configure permissions
       #- ChurchTools__EnableSync=true
       #- ChurchTools__Host=example.church.tools
       #- ChurchTools__LoginToken=DuIojxSyqCIMLf8JXEhQCshetSCZFP2dCuNIzHtgrKxqK13e80MdPY15wjt2jUNpWZzlCpEkJVTxYr6MCx3WZpmY5w8CeiwJbke1lKZ4GfD2jc3niVbiRI66obQtfJH8biXw2HXgZVbgMnK4aMQGOlY7Ssfp8SwyZMki1RoIYNBjWPAGAWyeAD5Dp1cApB74BqoWyziSTIE0EP6DQA8HV7n2IUZCVdgnlQkypcM7YeUTGiex57vdHrfH1foJvwax
+
+      # Uncomment these options and fill in your SMTP account
+      #- EmailDelivery__Enable=true
+      #- EmailDelivery__SenderAddress=noreply@example.org
+      #- EmailDelivery__SmtpHost=smtp.example.org
+      #- EmailDelivery__SmtpUsername=noreply@example.org
+      #- EmailDelivery__SmtpPassword=4mKrsCOoIUYm4FKumX57
+
+      # After configuring email delivery above, you may uncomment these options and fill in your catchall IMAP account
+      #- EmailRelay__Enable=true
+      #- EmailRelay__ImapHost=imap.example.org
+      #- EmailRelay__ImapUsername=catchall@example.org
+      #- EmailRelay__ImapPassword=RKXMaQWm8k7QKFnmijma
   db:
     image: mariadb:latest
     restart: unless-stopped