diff --git a/README.md b/README.md
index 593bea15..95ea1cdd 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,7 @@
-# remark42 [](https://github.com/umputun/remark42/actions) [](https://goreportcard.com/report/github.com/umputun/remark42) [](https://coveralls.io/github/umputun/remark42?branch=master) [](https://codecov.io/gh/umputun/remark42)
+# Remark42 [](https://github.com/umputun/remark42/actions) [](https://goreportcard.com/report/github.com/umputun/remark42) [](https://coveralls.io/github/umputun/remark42?branch=master) [](https://codecov.io/gh/umputun/remark42)
-
-
-Remark42 is a self-hosted, lightweight, and simple (yet functional) comment engine, which doesn't spy on users. It can be embedded into blogs, articles or any other place where readers add comments.
+Remark42 is a self-hosted, lightweight and simple (yet functional) comment engine, which doesn't spy on users. It can be embedded into blogs, articles, or any other place where readers add comments.
* Social login via Google, Twitter, Facebook, Microsoft, GitHub and Yandex
* Login via email
@@ -19,13 +17,13 @@ Remark42 is a self-hosted, lightweight, and simple (yet functional) comment engi
* RSS for all comments and each post
* Telegram, Slack and email notifications for Admins (get notified for each new comment)
* Email and Telegram notifications for users (get notified when someone responds to your comment)
-* Export data to json with automatic backups
+* Export data to JSON with automatic backups
* No external databases, everything embedded in a single data file
* Fully dockerized and can be deployed in a single command
-* Self-contained executable can be deployed directly to Linux, Windows and MacOS
+* Self-contained executable can be deployed directly to Linux, Windows and macOS
* Clean, lightweight and customizable UI with white and dark themes
* Multi-site mode from a single instance
-* Integration with automatic ssl (direct and via [nginx-le](https://github.com/umputun/nginx-le))
+* Integration with automatic SSL (direct and via [nginx-le](https://github.com/umputun/nginx-le))
* [Privacy focused](#privacy)
[Demo site](https://remark42.com/demo/) available with all authentication methods, including email auth and anonymous access.
@@ -33,7 +31,7 @@ Remark42 is a self-hosted, lightweight, and simple (yet functional) comment engi
Screenshots
Comments example:
-
+
For admin screenshots see [Admin UI wiki](https://github.com/umputun/remark42/wiki/Admin-UI)
-deprecated options
+Deprecated options
| Command line | Replacement | Environment | Replacement | Default | Description | Deprecation version |
| ------------------ | ------------- | ------------------ | ------------- | ------- | -------------- | ------------------- |
@@ -225,20 +230,20 @@ trouble with unrecognized command-line options in the future.
| auth.email.passwd | smtp.password | AUTH_EMAIL_PASSWD | SMTP_PASSWORD | | smtp password | 1.5.0 |
| auth.email.tls | smtp.tls | AUTH_EMAIL_TLS | SMTP_TLS | `false` | enable TLS | 1.5.0 |
| auth.email.timeout | smtp.timeout | AUTH_EMAIL_TIMEOUT | SMTP_TIMEOUT | `10s` | smtp timeout | 1.5.0 |
-| img-proxy | image-proxy.http2https | IMG_PROXY | IMAGE_PROXY_HTTP2HTTPS | `false` | enable http->https proxy for images | 1.5.0 |
-| notify.type | notify.users, notify.admins | NOTIFY_TYPE | NOTIFY_ADMINS, NOTIFY_USERS | 1.9.0 |
-| notify.email.notify_admin| notify.admins=email | NOTIFY_EMAIL_ADMIN | NOTIFY_ADMINS=email | 1.9.0 |
-| notify.telegram.token | telegram.token | NOTIFY_TELEGRAM_TOKEN | TELEGRAM_TOKEN | telegram token | 1.9.0 |
-| notify.telegram.timeout | telegram.timeout | NOTIFY_TELEGRAM_TIMEOUT | TELEGRAM_TIMEOUT | telegram timeout | 1.9.0 |
+| img-proxy | image-proxy.http2https | IMG_PROXY | IMAGE_PROXY_HTTP2HTTPS | `false` | enable HTTP->HTTPS proxy for images | 1.5.0 |
+| notify.type | notify.admins, notify.users | NOTIFY_TYPE | NOTIFY_ADMINS, NOTIFY_USERS | | | 1.9.0 |
+| notify.email.notify_admin | notify.admins=email | NOTIFY_EMAIL_ADMIN | NOTIFY_ADMINS=email | | | 1.9.0 |
+| notify.telegram.token | telegram.token | NOTIFY_TELEGRAM_TOKEN | TELEGRAM_TOKEN | | Telegram token | 1.9.0 |
+| notify.telegram.timeout | telegram.timeout | NOTIFY_TELEGRAM_TIMEOUT | TELEGRAM_TIMEOUT | | Telegram timeout | 1.9.0 |
##### Required parameters
-Most of the parameters have sane defaults and don't require customization. There are only a few parameters user has to define:
+Most of the parameters have sane defaults and don't require customization. There are only a few parameters the user has to define:
-1. `SECRET` - secret key, can be any long and hard-to-guess string.
-2. `REMARK_URL` - url pointing to your remark42 server, i.e. `https://demo.remark42.com`
-3. At least one pair of `AUTH__CID` and `AUTH__CSEC` defining oauth2 provider(s)
+1. `SECRET` - secret key, can be any long and hard-to-guess string
+2. `REMARK_URL` - URL pointing to your Remark42 server, i.e. `https://demo.remark42.com`
+3. At least one pair of `AUTH__CID` and `AUTH__CSEC` defining OAuth2 provider(s)
The minimal `docker-compose.yml` has to include all required parameters:
@@ -251,159 +256,161 @@ services:
restart: always
container_name: "remark42"
environment:
- - REMARK_URL=https://demo.remark42.com # url pointing to your remark42 server
+ - REMARK_URL=https://demo.remark42.com # URL pointing to your Remark42 server
- SITE=YOUR_SITE_ID # site ID, same as used for `site_id`, see "Setup on your website"
- SECRET=abcd-123456-xyz-$%^& # secret key
- - AUTH_GITHUB_CID=12345667890 # oauth2 client ID
- - AUTH_GITHUB_CSEC=abcdefg12345678 # oauth2 client secret
+ - AUTH_GITHUB_CID=12345667890 # OAuth2 client ID
+ - AUTH_GITHUB_CSEC=abcdefg12345678 # OAuth2 client secret
volumes:
- - ./var:/srv/var # persistent volume to store all remark42 data
+ - ./var:/srv/var # persistent volume to store all Remark42 data
```
#### Quick installation test
-To verify if remark has been properly installed, check a demo page at `${REMARK_URL}/web` URL. Make sure to include `remark` site id to `${SITE}` list.
+To verify if Remark42 has been properly installed, check a demo page at `${REMARK_URL}/web` URL. Make sure to include `remark` site ID to `${SITE}` list.
-#### Register oauth2 providers
+#### Register OAuth2 providers
-Authentication handled by external providers. You should setup oauth2 for all (or some) of them to allow users to make comments. It is not mandatory to have all of them, but at least one should be correctly configured.
+Authentication handled by external providers. You should setup OAuth2 for all (or some) of them to allow users to make comments. It is not mandatory to have all of them, but at least one should be correctly configured.
-##### Google Auth Provider
+##### Facebook Auth provider
-1. Create a new project: https://console.developers.google.com/project
-1. Choose the new project from the top right project dropdown (only if another project is selected)
-1. In the project Dashboard center pane, choose **"API Manager"**
-1. In the left Nav pane, choose **"Credentials"**
-1. In the center pane, choose **"OAuth consent screen"** tab. Fill in **"Product name shown to users"** and hit save.
-1. In the center pane, choose **"Credentials"** tab.
+1. From https://developers.facebook.com select **"My Apps"**/**"Add a new App"**
+2. Set **"Display Name"** and **"Contact email"**
+3. Choose **"Facebook Login"** and then **"Web"**
+4. Set "Site URL" to your domain, e.g.: `https://remark42.mysite.com`
+5. Under **"Facebook login"**/**"Settings"** fill "Valid OAuth redirect URIs" with your callback URL constructed as domain + `/auth/facebook/callback`
+6. Select **"App Review"** and turn public flag on. This step may ask you to provide a link to your privacy policy
+
+##### GitHub Auth provider
+
+1. Create a new **"OAuth App"**: https://github.com/settings/developers
+2. Fill **"Application Name"** and **"Homepage URL"** for your site
+3. Under **"Authorization callback URL"** enter the correct URL constructed as domain + `/auth/github/callback`, i.e. `https://remark42.mysite.com/auth/github/callback`
+4. Take note of the **Client ID** and **Client Secret**
+
+##### Google Auth provider
+
+1. Create a new project: https://console.cloud.google.com/projectcreate
+2. Choose the new project from the top right project dropdown (only if another project is selected)
+3. In the project Dashboard center pane, choose **"API Manager"**
+4. In the left Nav pane, choose **"Credentials"**
+5. In the center pane, choose **"OAuth consent screen"** tab. Fill in **"Product name shown to users"** and hit save
+6. In the center pane, choose **"Credentials"** tab
* Open the **"New credentials"** drop down
* Choose **"OAuth client ID"**
* Choose **"Web application"**
* Application name is freeform, choose something appropriate
- * Authorized origins is your domain ex: `https://remark42.mysite.com`
- * Authorized redirect URIs is the location of oauth2/callback constructed as domain + `/auth/google/callback`, ex: `https://remark42.mysite.com/auth/google/callback`
+ * Authorized origins is your domain, e.g.: `https://remark42.mysite.com`
+ * Authorized redirect URIs is the location of OAuth2/callback constructed as domain + `/auth/google/callback`, e.g.: `https://remark42.mysite.com/auth/google/callback`
* Choose **"Create"**
-1. Take note of the **Client ID** and **Client Secret**
+7. Take note of the **Client ID** and **Client Secret**
-_instructions for google oauth2 setup borrowed from [oauth2_proxy](https://github.com/bitly/oauth2_proxy)_
+_instructions for Google OAuth2 setup borrowed from [oauth2_proxy](https://github.com/bitly/oauth2_proxy)_
-##### GitHub Auth Provider
+##### Microsoft Auth provider
-1. Create a new **"OAuth App"**: https://github.com/settings/developers
-1. Fill **"Application Name"** and **"Homepage URL"** for your site
-1. Under **"Authorization callback URL"** enter the correct url constructed as domain + `/auth/github/callback`. ie `https://remark42.mysite.com/auth/github/callback`
-1. Take note of the **Client ID** and **Client Secret**
+1. Register a new application [using the Azure portal](https://docs.microsoft.com/en-us/graph/auth-register-app-v2)
+2. Under **"Authentication/Platform configurations/Web"** enter the correct URL constructed as domain + `/auth/microsoft/callback`, i.e. `https://example.mysite.com/auth/microsoft/callback`
+3. In **"Overview"** take note of the **Application (client) ID**
+4. Choose the new project from the top right project dropdown (only if another project is selected)
+5. Select **"Certificates & secrets"** and click on **"+ New Client Secret"**
-##### Facebook Auth Provider
+##### Twitter Auth provider
-1. From https://developers.facebook.com select **"My Apps"** / **"Add a new App"**
-1. Set **"Display Name"** and **"Contact email"**
-1. Choose **"Facebook Login"** and then **"Web"**
-1. Set "Site URL" to your domain, ex: `https://remark42.mysite.com`
-1. Under **"Facebook login"** / **"Settings"** fill "Valid OAuth redirect URIs" with your callback url constructed as domain + `/auth/facebook/callback`
-1. Select **"App Review"** and turn public flag on. This step may ask you to provide a link to your privacy policy.
+1. Create a new Twitter application https://developer.twitter.com/en/apps
+2. Fill **App name**, **Description** and **URL** of your site
+3. In the field **Callback URLs** enter the correct URL of your callback handler, e.g. domain + `/auth/twitter/callback`
+4. Under **Key and tokens** take note of the **Consumer API Key** and **Consumer API Secret key**. Those will be used as `AUTH_TWITTER_CID` and `AUTH_TWITTER_CSEC`
-#### Microsoft Auth Provider
+##### Yandex Auth provider
-1. Register a new application [using the Azure portal](https://docs.microsoft.com/en-us/graph/auth-register-app-v2).
-2. Under **"Authentication/Platform configurations/Web"** enter the correct url constructed as domain + `/auth/microsoft/callback`. i.e. `https://example.mysite.com/auth/microsoft/callback`
-3. In "Overview" take note of the **Application (client) ID**
-4. Choose the new project from the top right project dropdown (only if another project is selected)
-5. Select "Certificates & secrets" and click on "+ New Client Secret".
-
-##### Twitter Auth Provider
-
-1. Create a new twitter application https://developer.twitter.com/en/apps
-1. Fill **App name**, **Description** and **URL** of your site
-1. In the field **Callback URLs** enter the correct url of your callback handler e.g. domain + `/auth/twitter/callback`
-1. Under **Key and tokens** take note of the **Consumer API Key** and **Consumer API Secret key**. Those will be used as `AUTH_TWITTER_CID` and
- `AUTH_TWITTER_CSEC`
-
-##### Yandex Auth Provider
-
-1. Create a new **"OAuth App"**: https://oauth.yandex.com/client/new
-1. Fill **"App name"** for your site
-1. Under **Platforms** select **"Web services"** and enter **"Callback URI #1"** constructed as domain + `/auth/yandex/callback`. ie `https://remark42.mysite.com/auth/yandex/callback`
-1. Select **Permissions**. You need following permissions only from the **"Yandex.Passport API"** section:
- * Access to user avatar
+1. Create a new **"OAuth App"**: https://oauth.yandex.com/client/new
+2. Fill **"App name"** for your site
+3. Under **Platforms** select **"Web services"** and enter **"Callback URI #1"** constructed as domain + `/auth/yandex/callback`, i.e. `https://remark42.mysite.com/auth/yandex/callback`
+4. Select **Permissions**. You need the following permissions only from the **"Yandex.Passport API"** section:
+ * Access to the user avatar
* Access to username, first name and surname, gender
-1. Fill out the rest of fields if needed
-1. Take note of the **ID** and **Password**
+5. Fill out the rest of the fields if needed
+6. Take note of the **ID** and **Password**
-For more details refer to [Yandex OAuth](https://tech.yandex.com/oauth/doc/dg/concepts/about-docpage/) and [Yandex.Passport](https://tech.yandex.com/passport/doc/dg/index-docpage/) API documentation.
+For more details refer to [Yandex OAuth](https://yandex.com/dev/oauth/doc/dg/concepts/about.html) and [Yandex.Passport](https://yandex.com/dev/passport/doc/dg/index.html) API documentation.
-##### Anonymous Auth Provider
+##### Anonymous Auth provider
-Optionally, anonymous access can be turned on. In this case an extra `anonymous` provider will allow logins without any social login with any name satisfying 2 conditions:
+Optionally, anonymous access can be turned on. In this case, an extra `anonymous` provider will allow logins without any social login with any name satisfying 2 conditions:
-- name should be at least 3 characters long
-- name has to start from the letter and contains letters, numbers, underscores and spaces only.
+* name should be at least 3 characters long
+* name has to start from the letter and contains letters, numbers, underscores and spaces only
-### Importing comments
+#### Importing comments
-Remark supports importing comments from Disqus, WordPress or native backup format.
+Remark42 supports importing comments from Disqus, WordPress, or native backup format.
All imported comments have an `Imported` field set to `true`.
-## Initial import from Disqus
+##### Initial import from Disqus
-1. Disqus provides export of all comments on your site in a gzipped file. This option is available in your Moderation panel at Disqus Admin > Setup > Export. The export will be sent into a queue and then emailed to the address associated with your account once it's ready. Direct link to export will be something like `https://.disqus.com/admin/discussions/export/`. See [importing-exporting](https://help.disqus.com/customer/portal/articles/1104797-importing-exporting) for more details.
-2. Move this file to your remark42 host within `./var` and extract, i.e. `gunzip .xml.gz`.
-3. Run import command - `docker exec -it remark42 import -p disqus -f /srv/var/{disqus-export-name}.xml -s {your site id}`
+1. Disqus provides an export of all comments on your site in a gzipped file. This option is available in your Moderation panel at Disqus Admin > Setup > Export. The export will be sent into a queue and then emailed to the address associated with your account once it's ready. Direct link to export will be something like `https://.disqus.com/admin/discussions/export/`. See [importing-exporting](https://help.disqus.com/en/articles/1717199-importing-exporting) for more details
+2. Move this file to your Remark42 host within `./var` and extract, i.e. `gunzip .xml.gz`
+3. Run import command - `docker exec -it remark42 import -p disqus -f /srv/var/{disqus-export-name}.xml -s {your site ID}`
-## Initial import from WordPress
+##### Initial import from WordPress
-1. Use [that instruction](https://wordpress.com/support/export/) to export comments to file using standard WordPress functionality.
-2. Move this file to your remark42 host within `./var`
-3. Run import command - `docker exec -it remark42 import -p wordpress -f /srv/var/{wordpress-export-name}.xml -s {your site id}`
+1. Use [that instruction](https://wordpress.com/support/export/) to export comments to file using standard WordPress functionality
+2. Move this file to your Remark42 host within `./var`
+3. Run import command - `docker exec -it remark42 import -p wordpress -f /srv/var/{wordpress-export-name}.xml -s {your site ID}`
#### Backup and restore
##### Automatic backups
-Remark42 by default makes daily backup files under `${BACKUP_PATH}` (default `./var/backup`). Backups kept up to `${MAX_BACKUP_FILES}` (default 10). Each backup file contains exported and gzipped content, i.e., all comments. At any point, the user can restore such backup and revert all comments to the desirable state. Note: restore procedure cleans the current data store and replaces all comments with comments from the backup file.
+
+Remark42 by default makes daily backup files under `${BACKUP_PATH}` (default `./var/backup`). Backups kept up to `${MAX_BACKUP_FILES}` (default 10). Each backup file contains exported and gzipped content, i.e. all comments. At any point, the user can restore such backup and revert all comments to the desired state.
+
+**Note:** Restore procedure cleans the current data store and replaces all comments with comments from the backup file.
For safety and security reasons restore functionality not exposed outside of your server by default. The recommended way to restore from the backup is to use provided `scripts/restore-backup.sh`. It can run inside the container:
-`docker exec -it remark42 restore -f {backup-filename.gz} -s {your site id}`
+`docker exec -it remark42 restore -f {backup-filename.gz} -s {your site ID}`
##### Manual backup
-In addition to automatic backups user can make a backup manually. This command makes `userbackup-{site id}-{timestamp}.gz` by default.
+In addition to automatic backups, user can make a backup manually. This command makes `userbackup-{site ID}-{timestamp}.gz` by default.
-`docker exec -it remark42 backup -s {your site id}`
+`docker exec -it remark42 backup -s {your site ID}`
##### Restore from backup
-Restore will clean all comments first and then will processed with complete import from a given file.
+Restore will clean all comments first and then will process with complete import from a given file.
-`docker exec -it remark42 restore -f {backup file name} -s {your site id}`
+`docker exec -it remark42 restore -f {backup file name} -s {your site ID}`
##### Backup format
-Backup file is a text file with all exported comments separated by EOL. Each backup record is a valid json with all key/value
+The backup file is a text file with all exported comments separated by EOL. Each backup record is a valid JSON with all key/value
unmarshaled from `Comment` struct (see below).
#### Admin users
Admins/moderators should be defined in `docker-compose.yml` as a list of user IDs or passed in the command line.
-```
- environment:
- - ADMIN_SHARED_ID=github_ef0f706a79cc24b17bbbb374cd234a691a034128,github_dae9983158e9e5e127ef2b87a411ef13c891e9e5
+```yaml
+environment:
+ - ADMIN_SHARED_ID=github_ef0f706a79cc24b17bbbb374cd234a691a034128,github_dae9983158e9e5e127ef2b87a411ef13c891e9e5
```
-To get user id just login and click on your username or any other user you want to promote to admins.
-It will expand login info and show full user ID.
+To get a user ID just log in and click on your username or any other user you want to promote to admins.
+It will expand login info and show the full user ID.
#### Docker parameters
Two parameters allow customizing Docker container on the system level:
-- `APP_UID` - sets UID to run remark42 application in container (default=1001)
-- `TIME_ZONE` - sets time zone of remark42 container (default=America/Chicago)
+* `APP_UID` - sets UID to run Remark42 application in container (default=1001)
+* `TIME_ZONE` - sets time zone of Remark42 container (default=America/Chicago)
_see [umputun/baseimage](https://github.com/umputun/baseimage) for more details_
-example of `docker-compose.yml`:
+Example of `docker-compose.yml`:
```yaml
version: '2'
@@ -414,50 +421,49 @@ services:
restart: always
container_name: "remark42"
environment:
- - APP_UID=2000 # runs remark42 app with non-default UID
+ - APP_UID=2000 # runs Remark42 app with non-default UID
- TIME_ZONE=GTC # sets container time to UTC
- - REMARK_URL=https://demo.remark42.com # url pointing to your remark42 server
+ - REMARK_URL=https://demo.remark42.com # URL pointing to your Remark42 server
- SITE=YOUR_SITE_ID # site ID, same as used for `site_id`, see "Setup on your website"
- SECRET=abcd-123456-xyz-$%^& # secret key
- - AUTH_GITHUB_CID=12345667890 # oauth2 client ID
- - AUTH_GITHUB_CSEC=abcdefg12345678 # oauth2 client secret
+ - AUTH_GITHUB_CID=12345667890 # OAuth2 client ID
+ - AUTH_GITHUB_CSEC=abcdefg12345678 # OAuth2 client secret
volumes:
- - ./var:/srv/var # persistent volume to store all remark42 data
+ - ./var:/srv/var # persistent volume to store all Remark42 data
```
-
### Setup on your website
#### Comments
-It's a main widget which renders list of comments.
+It's the main widget that renders a list of comments.
Add this snippet to the bottom of web page:
```html