split docs by versions

2020-10-11 17:12:14 -05:00
parent bec6bcee0d
commit e52499316e
18 changed files with 413 additions and 0 deletions
@@ -0,0 +1,7 @@
+# Documentation and FAQ
+
+- [How to configure remark42 with nginx reverse proxy](nginx-proxy.md)
+- [How to configure remark42 without a subdomain](subdomain.md) with Nginx or Caddy
+- [Telegram notifications](telegram.md)
+- [Setup email authentication and\or email notifications](email.md)
+- [How to add new translation to remark42](translation.md)
@@ -0,0 +1,50 @@
+## How to configure remark42 with nginx reverse proxy
+
+Example of nginx configuration (reverse proxy) running remark42 service on remark42.example.com
+
+```
+server {
+    listen      443;
+    server_name remark42.example.com;
+    ssl    on;
+    ssl_certificate        /etc/nginx/ssl/remark42.example.com.crt;
+    ssl_certificate_key    /etc/nginx/ssl/remark42.example.com.key;
+
+    gzip on;
+    gzip_types text/plain application/json text/css application/javascript application/x-javascript text/javascript text/xml application/xml application/rss+xml application/atom+xml application/rdf+xml;
+    gzip_min_length 1000;
+    gzip_proxied any;
+
+
+    location ~ /\.git {
+        deny all;
+    }
+
+    location /index.html {
+         proxy_redirect          off;
+         proxy_set_header        X-Real-IP $remote_addr;
+         proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
+         proxy_set_header        Host $http_host;
+         proxy_pass              http://remark42:8080/web/index.html;
+     }
+
+    location / {
+         proxy_redirect          off;
+         proxy_set_header        X-Real-IP $remote_addr;
+         proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
+         proxy_set_header        Host $http_host;
+         proxy_pass              http://remark42:8080/;
+    }
+
+    access_log   /var/log/nginx/remark42.log;
+
+}
+
+server {
+  listen 80;
+  server_name remark42.example.com;
+  return      301 https://remark42.example.com$request_uri;
+}
+```
+
+note: `proxy_pass` points to internal DNS name `remark42` and expected to run from the same compose. If nginx runs outside of compose the real IP (or docker's bridge IP) should be used
@@ -0,0 +1,49 @@
+## How to add new language translation to Remark42
+
+Translation files are stored in [/frontend/app/locales](https://github.com/umputun/remark42/tree/master/frontend/app/locales)
+directory with `.json` extension and content like following:
+
+```json
+{
+  "anonymousLoginForm.length-limit": "Username must be at least 3 characters long",
+  "anonymousLoginForm.log-in": "Log in",
+  "anonymousLoginForm.symbol-limit": "Username must start from the letter and contain only latin letters, numbers, underscores, and spaces",
+<...>
+}
+```
+
+### How to add a new translation
+
+We truly appreciate people spending time contributing their translations to remark42. Please go through the steps
+below in order to have your translation start being available to all remark42 users and included in the next release.
+
+1. create a fork of [umputun/remark42](https://github.com/umputun/remark42) repo, and if you already have one please
+pull the latest changes from the upstream master branch. It could be done like that:
+   ```shell
+   git remote add upstream https://github.com/umputun/remark42.git
+   git fetch upstream
+   git rebase upstream/master
+   git push
+   ```
+1. add new locale with [two-letter code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
+of the language you want to make the translation into to list in
+[frontend/tasks/supportedLocales.json](https://github.com/umputun/remark42/blob/master/frontend/tasks/supportedLocales.json)
+1. run `npm run translation:generate` in `frontend` folder
+1. translate all values in the newly created json file in
+[frontend/app/locales/](https://github.com/umputun/remark42/blob/master/frontend/app/locales/)
+1. commit all changes above in your fork
+1. test your changes in the interface:
+    1. uncomment `locale: "ru"` line in [frontend/index.ejs](https://github.com/umputun/remark42/blob/master/frontend/index.ejs#L133)
+    and replace `ru` with your translation language code
+    1. [run remark42 in Docker](https://github.com/umputun/remark42#development) by issuing following commands
+    from the root directory of your remark42 fork:
+
+        ```shell
+        docker-compose -f compose-dev-frontend.yml build
+        docker-compose -f compose-dev-frontend.yml up
+        ```
+    1. open [http://127.0.0.1:8080](http://127.0.0.1:8080), log in, make a comment, make a reply to a comment,
+    and make sure that your translation looks as you expect it to look
+    1. make a screenshot from [http://127.0.0.1:8080](http://127.0.0.1:8080) with your translation in place
+1. after all previous steps are done, create a [Pull Request](https://github.com/umputun/remark42/pulls) to umputun/remark42
+repo with your changes, attaching a screenshot or two from your local test instance to it
@@ -0,0 +1,202 @@
+## Overview
+
+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:
+
+```
+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:
+
+```yaml
+- 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
+- NOTIFY_EMAIL_FROM=notify@example.com
+```
+
+#### API
+
+When you don't want to expose your IP (which is impossible with any SMTP provider)
+and for situations when connecting to external SMTP server is impossible due to firewall
+settings is setting up an SMTP-to-API bridge and sending messages trough it.
+
+To use any of containers below with in remark42 environment set following two `SMTP` variables:
+
+```yaml
+- SMTP_HOST=mail
+- SMTP_PORT=25
+```
+
+#### stevenolen/mailgun-smtp-server
+
+Here is `docker-compose.yml` configuration part spinning up a container for
+[stevenolen/mailgun-smtp-server](https://hub.docker.com/r/stevenolen/mailgun-smtp-server):
+```yaml
+    mailgun:
+        image: stevenolen/mailgun-smtp-server
+        container_name: "mail"
+        hostname: "mail"
+
+        logging:
+            driver: json-file
+            options:
+                max-size: "10m"
+                max-file: "5"
+
+        environment:
+            - MG_KEY=key-123456789
+            - MG_DOMAIN=example.com
+```
+
+Please note that before
+[stevenolen/mailgun-smtp-server#5](https://github.com/stevenolen/mailgun-smtp-server/issues/5)
+is fixed, Europe domain names are not supported by this tool.
+
+### SendGrid
+
+This is an example of a configuration using [SendGrid](https://sendgrid.com/) email service:
+
+```yaml
+- SMTP_HOST=smtp.sendgrid.net
+- SMTP_PORT=465
+- SMTP_TLS=true
+- SMTP_USERNAME=apikey
+- SMTP_PASSWORD=key-123456789
+- AUTH_EMAIL_FROM=notify@example.com
+- NOTIFY_EMAIL_FROM=notify@example.com
+```
+
+#### API
+
+When you don't want to expose your IP (which is impossible with any SMTP provider)
+and for situations when connecting to external SMTP server is impossible due to firewall
+settings is setting up an SMTP-to-API bridge and sending messages trough it.
+
+To use any of containers below with in remark42 environment set following two `SMTP` variables:
+
+```yaml
+- SMTP_HOST=mail
+- SMTP_PORT=25
+```
+
+#### fgribreau/smtp-to-sendgrid-gateway
+
+Here is `docker-compose.yml` configuration part spinning up a container for
+[fgribreau/smtp-to-sendgrid-gateway](https://hub.docker.com/r/fgribreau/smtp-to-sendgrid-gateway):
+```yaml
+    sendgrid:
+        image: fgribreau/smtp-to-sendgrid-gateway
+        container_name: "mail"
+        hostname: "mail"
+
+        logging:
+            driver: json-file
+            options:
+                max-size: "10m"
+                max-file: "5"
+
+        environment:
+            - SENDGRID_API=key-123456789
+```
+
+### Gmail
+
+Configuration example for Gmail:
+
+```yaml
+- 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
+- NOTIFY_EMAIL_FROM=example.user@gmail.com
+```
+
+### Amazon SES
+
+Configuration example for [Amazon SES](https://aws.amazon.com/ses/) (us-east-1 region):
+```yaml
+- SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+- SMTP_PORT=465
+- SMTP_TLS=true
+- SMTP_USERNAME=access_key_id
+- SMTP_PASSWORD=secret_access_key
+- AUTH_EMAIL_FROM=notify@example.com
+- NOTIFY_EMAIL_FROM=notify@example.com
+```
+
+A domain or an email that will be used in `AUTH_EMAIL_FROM` or `NOTIFY_EMAIL_FROM` must first be [verified](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domain-procedure.html).
+
+[SMTP Credentials](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/smtp-credentials.html) must first be obtained from [Amazon SES Console](https://console.aws.amazon.com/ses/home?region=us-east-1#smtp-settings:):
+
+## 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
+```
+
+After you set `SMTP_` variables, you can allow email authentication by setting these two variables:
+
+```yaml
+- AUTH_EMAIL_ENABLE=true
+- AUTH_EMAIL_FROM=notify@example.com
+```
+
+
+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:
+
+```yaml
+NOTIFY_TYPE
+NOTIFY_EMAIL_FROM
+NOTIFY_EMAIL_VERIFICATION_SUBJ
+# for administrator notifications for new comments on their site
+ADMIN_SHARED_EMAIL
+NOTIFY_EMAIL_ADMIN
+```
+
+After you set `SMTP_` variables, you can allow email notifications by setting these two variables:
+
+```yaml
+- 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
+```
@@ -0,0 +1,73 @@
+## How to configure remark42 without a subdomain
+
+All README examples show configurations with remark42 on its own subdomain, i.e. `https://remark42.example.com`. However, it is possible and sometimes desirable to run remark42 without a subdomain, but just under some path, i.e.  `https://example.com/remark42`.
+
+- The frontend URL looks like this: `s.src = 'https://example.com/remark42/web/embed.js;`
+
+- The backend `REMARK_URL` parameter will be `https://example.com/remark42`
+
+- And you also need to slightly modify the callback URL for the social media login API's:
+  - Facebook Valid OAuth Redirect URIs: `https://example.com/remark42/auth/facebook/callback`
+  - Google Authorized redirect URIs: `https://example.com/remark42/auth/google/callback`
+  - Github Authorised callback URL: `https://example.com/remark42/auth/github/callback`
+
+### docker-compose configuration
+
+Both Nginx and Caddy configuration below relies on remark42 available on hostname `remark42`, which is achieved by having `container_name: remark42` in docker-compose.
+
+Example `docker-compose.yaml`:
+
+```yaml
+version: '2'
+services:
+  remark42:
+    image: umputun/remark42:latest
+    container_name: remark42
+    restart: always
+    environment:
+        - REMARK_URL=https://example.com/remark42/
+        - SITE=<site_ID>
+        - SECRET=<secret>
+        - ADMIN_SHARED_ID=<shared_id>
+    volumes:
+        - ./data:/srv/var
+    logging:
+        options:
+            max-size: "10m"
+            max-file: "1"
+```
+
+### Nginx configuration
+
+The `nginx.conf` would then look something like:
+
+```
+  location /remark42/ {
+    rewrite /remark42/(.*) /$1 break;
+    proxy_pass http://remark42:8080/; // use internal docker name of remark42 container for proxy
+    proxy_set_header Host $http_host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+```
+
+### Caddy configuration
+
+Example of Caddy configuration (`Caddyfile`) running remark42 service on `example.com/remark42/`:
+
+```caddy
+example.com {
+	gzip
+	tls mail@example.com
+
+	root /srv/www
+	log  /logs/access.log
+
+	# remark42
+	proxy /remark42/ http://remark42:8080/ {
+		without /remark42
+		transparent	
+	}
+}
+```
@@ -0,0 +1,32 @@
+## Telegram notifications
+
+In order to integrate notifications from remark42 with the [telegram](https://telegram.org), you should make [a channel](https://telegram.org/faq_channels) and obtain a token. This token should be used as `NOTIFY_TELEGRAM_TOKEN`. You also need to set `NOTIFY_TYPE=telegram` and set `NOTIFY_TELEGRAM_CHAN` to your channel. 
+
+In order to get token "just talk to [BotFather](https://core.telegram.org/bots#6-botfather)". All you need is to send `/newbot` command, choose bot name and the name for your bot (it must end in `bot`). This is it, you got a token. 
+
+_Example of such a "talk":_
+
+```
+Umputun:
+/newbot
+
+BotFather:
+Alright, a new bot. How are we going to call it? Please choose a name for your bot.
+
+Umputun:
+example_comments
+
+BotFather:
+Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
+
+Umputun:
+example_comments_bot
+
+BotFather:
+Done! Congratulations on your new bot. You will find it at t.me/example_comments_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.
+
+Use this token to access the HTTP API:
+12345678:xy778Iltzsdr45tg
+
+For a description of the Bot API, see this page: https://core.telegram.org/bots/api
+```