Update documentation for email capabilities (#555)

* replace deprecated email variables names with new ones * clarify email authentication instructions * add email notifications documentation * add explanation screenshots * fix punctuation and typos
2020-01-16 11:20:33 -06:00
parent b0898cd1f3
commit 8148650247
4 changed files with 83 additions and 33 deletions
@@ -3,5 +3,5 @@
 - [How to configure remark42 with nginx reverse proxy](nginx-proxy.md)
 - [How to configure remark42 without a subdomain](subdomain.md)
 - [Telegram notifications](telegram.md)
- [Setup email authentication](email.md)
+- [Setup email authentication and\or email notifications](email.md)
 
@@ -1,46 +1,96 @@
-## Setup email authentication
+## Overview

-To allow email auth `AUTH_EMAIL_ENABLE` should be set to `true`. In addition, user needs to configure SMTP details with
+This documentation describes how to enable the email-related capabilities of Remark.
+
+- email authentication for users:
+
+    enabling this will let the user log in using their emails:
+
+    ![Email authentication](/docs/images/email_auth.png?raw=true)
+
+- email notifications for any users except anonymous:
+
+    GitHub or Google or Twitter or any other kind of user gets the ability to get email notifications about new replies to their comments:
+
+    ![Email notifications subscription](/docs/images/email_notifications.png?raw=true)
+
+## Setup email server connection
+
+To enable any of email functionality you need to set up email (SMTP) server connection using these variables:

 ```
-AUTH_EMAIL_HOST         
-AUTH_EMAIL_PORT         
-AUTH_EMAIL_FROM         
-AUTH_EMAIL_SUBJ         
-AUTH_EMAIL_CONTENT_TYPE 
-AUTH_EMAIL_TLS          
-AUTH_EMAIL_USER         
-AUTH_EMAIL_PASSWD       
-AUTH_EMAIL_TIMEOUT      
+SMTP_HOST
+SMTP_PORT
+SMTP_TLS
+SMTP_USERNAME
+SMTP_PASSWORD
+SMTP_TIMEOUT
+```
+
+### Mailgun
+
+This is an example of a configuration using [Mailgun](https://www.mailgun.com/) email service:
+
+```
+      - SMTP_HOST=smtp.eu.mailgun.org
+      - SMTP_PORT=465
+      - SMTP_TLS=true
+      - SMTP_USERNAME=postmaster@mg.example.com
+      - SMTP_PASSWORD=secretpassword
+      - AUTH_EMAIL_FROM=notify@example.com
+```
+
+### Gmail
+
+Configuration example for Gmail:
+
+```
+      - SMTP_HOST=smtp.gmail.com
+      - SMTP_PORT=465
+      - SMTP_TLS=true
+      - SMTP_USERNAME=example.user@gmail.com
+      - SMTP_PASSWORD=secretpassword
+      - AUTH_EMAIL_FROM=example.user@gmail.com
+```
+
+
+## Setup email authentication
+
+Here is the list of variables which affect email authentication:
+
+```
+AUTH_EMAIL_ENABLE
+AUTH_EMAIL_FROM
+AUTH_EMAIL_SUBJ
+AUTH_EMAIL_CONTENT_TYPE
 AUTH_EMAIL_TEMPLATE
 ```

-This is an example of configuration using mailgun email service:
+After `SMTP_` variables are set, you can allow email authentication by setting these two variables:

 ```
      - AUTH_EMAIL_ENABLE=true
-      - AUTH_EMAIL_HOST=smtp.mailgun.org
-      - AUTH_EMAIL_PORT=465
-      - AUTH_EMAIL_TLS=true
-      - AUTH_EMAIL_USER=postmaster@mg.example.com
-      - AUTH_EMAIL_PASSWD=*********
-      - AUTH_EMAIL_FROM=confirmation@example.com
+      - AUTH_EMAIL_FROM=notify@example.com
 ```

-Configuration example for gmail:

-```
-      - AUTH_EMAIL_ENABLE=true
-      - AUTH_EMAIL_HOST=smtp.gmail.com
-      - AUTH_EMAIL_PORT=465
-      - AUTH_EMAIL_FROM=example.user@gmail.com
-      - AUTH_EMAIL_SUBJ=Comments email confirmation
-      - AUTH_EMAIL_TLS=true
-      - AUTH_EMAIL_USER=example.user@gmail.com
-      - AUTH_EMAIL_PASSWD=secretpassword
-```
-
-Usually you don't need to change/set anything else. In case if you want to use a different email template set `AUTH_EMAIL_TEMPLATE`, for instance
+Usually, you don't need to change/set anything else. In case if you want to use a different email template set `AUTH_EMAIL_TEMPLATE`, for instance
 `- AUTH_EMAIL_TEMPLATE="Confirmation email, token: {{.Token}}"`. See [verified-authentication](https://github.com/go-pkgz/auth#verified-authentication) for more details.

- 
+## Setup email notifications
+
+Here is the list of variables which affect email notifications:
+
+```
+NOTIFY_TYPE
+NOTIFY_EMAIL_FROM
+NOTIFY_EMAIL_VERIFICATION_SUBJ
+```
+
+After `SMTP_` variables are set, you can allow email notifications by setting these two variables:
+
+```
+      - NOTIFY_TYPE=email
+      # - NOTIFY_TYPE=email,telegram # this is in case you want to have both email and telegram notifications enabled
+      - NOTIFY_EMAIL_FROM=notify@example.com
+```