add documentation on running remark42 on a separate domain

umputun · Jun 30, 2022 · b00c970 · b00c970
1 parent 6a5c5a4
commit b00c970
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 0 deletions.
diff --git a/site/src/docs/manuals/separate-domain/index.md b/site/src/docs/manuals/separate-domain/index.md
@@ -0,0 +1,26 @@
+---
+title: Configure Instance on a different domain
+---
+
+## How to configure single remark42 instance for multiple domains
+
+### What doesn't work so far
+
+Unless discussion [1139](https://github.com/umputun/remark42/discussions/1139) has a marked answer, authorisation using oAuth like GitHub or Google is not possible on domains other than original one. Telegram, Email and anonymous auth would work everywhere.
+
+### Setup
+
+Set `ALLOWED_HOSTS='self',example1.org,example2.org` with your domain names and `AUTH_SAME_SITE=none`. `'self'` means "domain which remark42 is installed on" so you don't need to write it twice.
+
+### Technical details
+
+`ALLOWED_HOSTS` sets CSP [frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors), which, once enabled, limits the domains where remark42 would work. Default value is not set, so it would work on any domains.
+
+`AUTH_SAME_SITE` sets [SAME_SITE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) attribute for authorisation cookies which allows to use remark42 either on original domain and subdomains there  (default value, not set which equals to `Lax`) or allow setting authorisation cookies on any domain where remark42 is shown (`None` setting).
+
+Here are all possible combinations of these two:
+
+- Default setup with unaltered variables: comments are shown on any domain but the authorisation wouldn't work anywhere but on the same domain remark42 is installed on and subdomains of it.
+- `ALLOWED_HOSTS` set to a set of domains: comments are shown only on listed domains, authorisation wouldn't work anywhere but on the same domain remark42 is installed on and subdomains of it.
+- `AUTH_SAME_SITE` set to `None`: comments are shown on any domain, authorisation would work anywhere.
+- `ALLOWED_HOSTS` set to a set of domains and `AUTH_SAME_SITE` set to `None`: comments are shown on listed domains, authorisation would work on all of them.
diff --git a/site/src/docs/nav.json b/site/src/docs/nav.json
@@ -48,6 +48,10 @@
         "title": "Without subdomain",
         "href": "/manuals/subdomain/"
       },
+      {
+        "title": "On a separate domain",
+        "href": "/manuals/separate-domain/"
+      },
       {
         "title": "Reproxy",
         "href": "/manuals/reproxy/"