diff --git a/docs/1.6/README.md b/docs/1.6/README.md new file mode 100644 index 00000000..d54c0310 --- /dev/null +++ b/docs/1.6/README.md @@ -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) diff --git a/docs/email.md b/docs/1.6/email.md similarity index 100% rename from docs/email.md rename to docs/1.6/email.md diff --git a/docs/images/email_auth.png b/docs/1.6/images/email_auth.png similarity index 100% rename from docs/images/email_auth.png rename to docs/1.6/images/email_auth.png diff --git a/docs/images/email_notifications.png b/docs/1.6/images/email_notifications.png similarity index 100% rename from docs/images/email_notifications.png rename to docs/1.6/images/email_notifications.png diff --git a/docs/1.6/nginx-proxy.md b/docs/1.6/nginx-proxy.md new file mode 100644 index 00000000..385c15ed --- /dev/null +++ b/docs/1.6/nginx-proxy.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 \ No newline at end of file diff --git a/docs/subdomain.md b/docs/1.6/subdomain.md similarity index 100% rename from docs/subdomain.md rename to docs/1.6/subdomain.md diff --git a/docs/telegram.md b/docs/1.6/telegram.md similarity index 100% rename from docs/telegram.md rename to docs/1.6/telegram.md diff --git a/docs/1.6/translation.md b/docs/1.6/translation.md new file mode 100644 index 00000000..5c7834bf --- /dev/null +++ b/docs/1.6/translation.md @@ -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 diff --git a/docs/README.md b/docs/latest/README.md similarity index 100% rename from docs/README.md rename to docs/latest/README.md diff --git a/docs/developers-guide/email-templates.md b/docs/latest/developers-guide/email-templates.md similarity index 100% rename from docs/developers-guide/email-templates.md rename to docs/latest/developers-guide/email-templates.md diff --git a/docs/latest/email.md b/docs/latest/email.md new file mode 100644 index 00000000..70279541 --- /dev/null +++ b/docs/latest/email.md @@ -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 +``` diff --git a/docs/latest/images/email_auth.png b/docs/latest/images/email_auth.png new file mode 100644 index 00000000..91992610 Binary files /dev/null and b/docs/latest/images/email_auth.png differ diff --git a/docs/latest/images/email_notifications.png b/docs/latest/images/email_notifications.png new file mode 100644 index 00000000..d066c42d Binary files /dev/null and b/docs/latest/images/email_notifications.png differ diff --git a/docs/nginx-proxy.md b/docs/latest/nginx-proxy.md similarity index 100% rename from docs/nginx-proxy.md rename to docs/latest/nginx-proxy.md diff --git a/docs/spa.md b/docs/latest/spa.md similarity index 100% rename from docs/spa.md rename to docs/latest/spa.md diff --git a/docs/latest/subdomain.md b/docs/latest/subdomain.md new file mode 100644 index 00000000..5f7cb54b --- /dev/null +++ b/docs/latest/subdomain.md @@ -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= + - SECRET= + - ADMIN_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 + } +} +``` diff --git a/docs/latest/telegram.md b/docs/latest/telegram.md new file mode 100644 index 00000000..42aaf347 --- /dev/null +++ b/docs/latest/telegram.md @@ -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 +``` diff --git a/docs/translation.md b/docs/latest/translation.md similarity index 100% rename from docs/translation.md rename to docs/latest/translation.md