root: global email settings (#448)

* root: make global email settings configurable

* stages/email: add use_global_settings

* stages/email: add test_email command to test email sending

* stages/email: update email template

* stages/email: simplify email template path

* stages/email: add support for user-supplied email templates

* stages/email: add tests for sending and templates

* stages/email: only add custom template if permissions are correct

* docs: add custom email template docs

* root: add /templates volume in docker-compose by default

* stages/email: fix form not allowing custom templates

* stages/email: use relative path for custom templates

* stages/email: check if all templates exist on startup, reset

* docs: add global email docs for docker-compose

* helm: add email config to helm chart

* helm: load all secrets with env prefix

* helm: move s3 and smtp secret to secret

* stages/email: fix test for relative name

* stages/email: add argument to send email from existing stage

* stages/email: set uid using slug of message id

* stages/email: ensure template validation ignores migration runs

* docs: add email troubleshooting docs

* stages/email: fix long task_name breaking task list

website/docs/flow/stages/email/index.md

@@ -5,3 +5,19 @@ title: Email stage
 This stage can be used for email verification. authentik's background worker will send an email using the specified connection details. When an email can't be delivered, delivery is automatically retried periodically.
 
 ![](email-recovery.png)
+
+## Custom Templates
+
+You can also use custom email templates, to use your own design or layout.
+
+Place any custom templates in the `custom-templates` Folder, which is in the same folder as your docker-compose file. Afterwards, you'll be able to select the template when creating/editing an Email stage.
+
+:::info
+This is currently only supported for docker-compose installs, and supported starting version 0.15.
+:::
+
+:::info
+If you've add the line and created a file, and can't see if, check the logs using `docker-compose logs -f worker`.
+:::
+
+![](custom-template.png)

website/docs/index.md

@@ -9,7 +9,7 @@ authentik is an open-source Identity Provider focused on flexibility and versati
 
 ## Installation
 
-See [Docker-compose](installation/docker-compose.md) or [Kubernetes](installation/kubernetes.md)
+See [Docker-compose](installation/docker-compose) or [Kubernetes](installation/kubernetes)
 
 ## Screenshots
 

website/docs/installation/docker-compose.md

@@ -9,7 +9,7 @@ This installation method is for test-setups and small-scale productive setups.
 -   docker
 -   docker-compose
 
-## Install
+## Preparation
 
 Download the latest `docker-compose.yml` from [here](https://raw.githubusercontent.com/BeryJu/authentik/master/docker-compose.yml). Place it in a directory of your choice.
 
@@ -25,6 +25,30 @@ echo "PG_PASS=$(pwgen 40 1)" >> .env
 echo "AUTHENTIK_SECRET_KEY=$(pwgen 50 1)" >> .env
 ```
 
+## Email configuration (optional, but recommended)
+
+It is also recommended to configure global email credentials. These are used by authentik to notify you about alerts, configuration issues. They can also be used by [Email stages](flow/stages/email/index.md) to send verification/recovery emails.
+
+Append this block to your `.env` file
+
+```
+# SMTP Host Emails are sent to
+AUTHENTIK_EMAIL__HOST=localhost
+AUTHENTIK_EMAIL__PORT=25
+# Optionally authenticate
+AUTHENTIK_EMAIL__USERNAME=""
+AUTHENTIK_EMAIL__PASSWORD=""
+# Use StartTLS
+AUTHENTIK_EMAIL__USE_TLS=false
+# Use SSL
+AUTHENTIK_EMAIL__USE_SSL=false
+AUTHENTIK_EMAIL__TIMEOUT=10
+# Email address authentik will send from, should have a correct @domain
+AUTHENTIK_EMAIL__FROM=authentik@localhost
+```
+
+## Startup
+
 Afterwards, run these commands to finish
 
 ```
@@ -39,8 +63,6 @@ If you plan to use this setup for production, it is also advised to change the P
 
 Now you can pull the Docker images needed by running `docker-compose pull`. After this has finished, run `docker-compose up -d` to start authentik.
 
-authentik will then be reachable via HTTP on port 80, and HTTPS on port 443. You can optionally configure the packaged traefik to use Let's Encrypt certificates for TLS Encryption.
-
-If you plan to access authentik via a reverse proxy which does SSL Termination, make sure you use the HTTPS port, so authentik is aware of the SSL connection.
+authentik will then be reachable HTTPS on port 443. You can optionally configure the packaged traefik to use Let's Encrypt certificates for TLS Encryption.
 
 The initial setup process also creates a default admin user, the username and password for which is `akadmin`. It is highly recommended to change this password as soon as you log in.

website/docs/installation/kubernetes.md

@@ -14,6 +14,8 @@ helm install authentik/authentik --devel -f values.yaml
 
 This installation automatically applies database migrations on startup. After the installation is done, you can use `akadmin` as username and password.
 
+It is also recommended to configure global email credentials. These are used by authentik to notify you about alerts, configuration issues. They can also be used by [Email stages](flow/stages/email/index.md) to send verification/recovery emails.
+
 ```yaml
 ###################################
 # Values directly affecting authentik
@@ -41,6 +43,21 @@ config:
     # Log level used by web and worker
     # Can be either debug, info, warning, error
     logLevel: warning
+    # Global Email settings
+    email:
+        # SMTP Host Emails are sent to
+        host: localhost
+        port: 25
+        # Optionally authenticate
+        username: ""
+        password: ""
+        # Use StartTLS
+        useTls: false
+        # Use SSL
+        useSsl: false
+        timeout: 10
+        # Email address authentik will send from, should have a correct @domain
+        from: authentik@localhost
 
 # Enable Database Backups to S3
 # backup:
@@ -80,6 +97,4 @@ redis:
     master:
         persistence:
             enabled: false
-        # https://stackoverflow.com/a/59189742
-        disableCommands: []
 ```

website/docs/troubleshooting/emails.md

@@ -0,0 +1,23 @@
+---
+title: Troubleshooting Email sending
+---
+
+To test if an email stage, or the global email settings are configured correctly, you can run the following command:
+
+````
+./manage.py test_email <to address> [-s <stage name>]
+```
+
+If you omit the `-s` parameter, the email will be sent using the global settings. Otherwise, the settings of the specified stage will be used.
+
+To run this command with docker-compose, use
+
+```
+docker-compose exec -it worker ./manage.py test_email [...]
+```
+
+To run this command with Kubernetes, use
+
+```
+kubectl exec -it authentik-worker-xxxxx -- ./manage.py test_email [...]
+```