update backup documentation

Few things here: 1. Merge automatic and manual backup to a single page 2. State that ADMIN_PASSWD must be enabled for backup or restore to work 3. Remove unneeded usage of --admin-passwd from commands inside the container 4. Make the main backups page (not clickable through the interface, available only in search) redirect to information about backups instead of displaying text 5. Add HTTPS port to canonical docker-compose.yml 6. Clarify build option in the canonical docker-compose.yaml
ab5169 · Jul 25, 2022 · 0aa6052eba5c8567bca5a1dec21a1757b71a1553 · 0aa6052
1 parent f25b34d
commit 0aa6052eba5c8567bca5a1dec21a1757b71a1553
Show file tree

Hide file tree

Showing 11 changed files with 51 additions and 60 deletions.
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -2,6 +2,8 @@ version: "2"
 
 services:
   remark:
+    # remove the next line in case you want to use this docker-compose separately
+    # as otherwise it would complain for absence of Dockerfile
     build: .
     image: umputun/remark42:latest
     container_name: "remark42"
@@ -17,6 +19,7 @@ services:
     # uncomment to expose directly (no proxy)
     #ports:
     #  - "80:8080"
+    #  - "443:8443"
 
     environment:
       - REMARK_URL
@@ -30,6 +33,9 @@ services:
       - AUTH_FACEBOOK_CSEC
       - AUTH_DISQUS_CID
       - AUTH_DISQUS_CSEC
-      # - ADMIN_PASSWD=password
+      # Enable it only for the initial comment import or for manual backups.
+      # Do not leave server running with ADMIN_PASSWD set if you don't have intention
+      # to keep creating backups manually!
+      # - ADMIN_PASSWD=<your secret password>
     volumes:
       - ./var:/srv/var
diff --git a/site/src/docs/backup/automatic/index.md b/site/src/docs/backup/automatic/index.md
diff --git a/site/src/docs/backup/backup/index.md b/site/src/docs/backup/backup/index.md
@@ -0,0 +1,20 @@
+---
+title: Automatic and Manual Backup
+---
+
+## Automatic
+
+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:** The [restore procedure](https://remark42.com/docs/backup/restore/) cleans the current data store and replaces all comments from the backup file.
+
+## Manual
+
+You can make a backup manually whenever you want. Run the command (`ADMIN_PASSWD` must be enabled on the server for it to work):
+`docker exec -it remark42 backup -s {your site ID}`
+
+This command creates `userbackup-{site ID}-{timestamp}.gz` file by default.
+
+## Backup format
+
+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 the `Comment` struct (see [here](https://remark42.com/docs/contributing/api/#commenting)).
diff --git a/site/src/docs/backup/index.md b/site/src/docs/backup/index.md
@@ -1,7 +1,4 @@
 ---
-title: Backup
+layout: redirect.njk
+destination: /docs/backup/backup/
 ---
-
-### Backup format
-
-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 the `Comment` struct (see [here](https://remark42.com/docs/contributing/api/#commenting)).
diff --git a/site/src/docs/backup/manual/index.md b/site/src/docs/backup/manual/index.md
diff --git a/site/src/docs/backup/migration/index.md b/site/src/docs/backup/migration/index.md
@@ -1,22 +1,22 @@
 ---
-title: Migration
+title: Migration from Disqus/WordPress/Commento to Remark42
 ---
 
-Remark42 supports importing comments from Disqus, WordPress, Commento, or native backup format. All imported comments have an `Imported` field set to `true`. All methods below remove existing comments from the site if they are present, please use the last paragraph to preserve them.
+Remark42 supports importing comments from Disqus, WordPress, Commento, or native backup format. All imported comments have an `Imported` field set to `true`. All methods below remove existing comments from the site if they are present, please see the [restoration documentation](https://remark42.com/docs/backup/restore/) for instructions on import preserving existing comments.
 
 ### 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://<siteud>.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 <disqus-export-name>.xml.gz`
-3. Run import command - `docker exec -it remark42 import -p disqus -f /srv/var/{disqus-export-name}.xml -s {your site ID}`
+3. Run import command (`ADMIN_PASSWD` must to be enabled on server for it to work) - `docker exec -it remark42 import -p disqus -f /srv/var/{disqus-export-name}.xml -s {your site ID}`
 
 ### 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}`
+3. Run import command (`ADMIN_PASSWD` must to be enabled on server for it to work) - `docker exec -it remark42 import -p wordpress -f /srv/var/{wordpress-export-name}.xml -s {your site ID}`
 
 ### Initial import from Commento
 
 1. Move exported json file to your Remark42 host within `./var`
-2. Run import command - `docker exec -it remark42 import -p commento -f /srv/var/{commento-export-name}.json -s {your site ID}`
+2. Run import command (`ADMIN_PASSWD` must to be enabled on server for it to work) - `docker exec -it remark42 import -p commento -f /srv/var/{commento-export-name}.json -s {your site ID}`
diff --git a/site/src/docs/backup/restore/index.md b/site/src/docs/backup/restore/index.md
@@ -4,11 +4,13 @@ title: Restore Backup
 
 Restore will clean all comments first and then process with complete import from a given file.
 
-`docker exec -it remark42 restore -f {backup file name} -s {your site ID}`
+For safety and security reasons, restore functionality not exposed outside your server by default. The recommended way to restore from the backup is to use provided `scripts/restore.sh`. It can run inside the container (`ADMIN_PASSWD` must to be enabled on server for it to work):
+
+`docker exec -it remark42 restore -f {backup-filename.gz} -s {your site ID}`
 
 ### Import/restore without removing existing comments
 
-All methods above nuke the existing comments on the site. You should make two backup files to preserve them, one for the current remark42 content and another for imported WP/Discuss/Commento content. The format of backups is plain JSON with EOL (JSON line) and can be easily constructed from multiple sources. Merge them and restore them from the resulting file:
+The `restore` command nukes the existing comments on the site. You should make two backup files to preserve them, one for the current remark42 content and another for WP/Discuss/Commento content you want to import. The format of backups is plain JSON with EOL (JSON line) and can be easily constructed from multiple sources. Merge them and restore them from the resulting file:
 
 ```shell
 cat wp-export.json | grep -v '{"version":1' >> combined-export.json

diff --git a/site/src/docs/backup/url-migration/index.md b/site/src/docs/backup/url-migration/index.md
@@ -17,31 +17,20 @@ https://example.org/old-url-2/ https://example.org/new-url-2/
 
 ### Applying the remap
 
-After rules file is ready, run the following command:
+After rules file is ready, run the following command (`ADMIN_PASSWD` must to be enabled on server for it to work):
 
 ```shell
-remark42 remap --admin-passwd <password> -f var/rules
+remark42 remap --admin-passwd <password> -s <your site ID> -f var/rules
 ```
 
-If running in a docker container, the command becomes:
+If running in a docker container, the command becomes (`ADMIN_PASSWD` will be taken from the environment):
 
 ```shell
-docker ps # to find the container name
-docker exec -it <container> remark42 remap --admin-passwd <password> -f var/rules
+docker exec -it remark42 remap -s <your site ID> -f var/rules
 ```
 
-#### Tips
-
-1. The command above sends a *request* to start the remap job. You can see the job execution logs by running:
+The command above sends a *request* to start the remap job. You can see the job execution logs by running:
 
 ```shell
 docker logs <container>
 ```
-
-2. If you see in logs an entry similar to `export failed with site "site1.com,site2" not found`, please run the command again and specify desired site with command line arguments. For example:
-
-```shell
-docker exec -it <container> remark42 remap --admin-passwd <password> -f var/rules --site site1.com
-``` 
-
-
diff --git a/site/src/docs/contributing/technical-details/index.md b/site/src/docs/contributing/technical-details/index.md
@@ -16,7 +16,7 @@ User's activity throttled globally (up to 1000 simultaneous requests) and limite
 
 Request timeout set to 60sec.
 
-Admin authentication (`--admin-password` set) allows to hit Remark42 API without social login and admin privileges. Adds basic-auth for username: `admin`, password: `${ADMIN_PASSWD}`.
+Admin authentication (`--admin-password` set) allows to hit Remark42 API without social login and admin privileges. Adds basic-auth for username: `admin`, password: `${ADMIN_PASSWD}`. Enable it only for the initial comment import or for manual backups. Do not leave server running with admin password set if you don't have intention to keep creating backups manually!
 
 User can vote for the comment multiple times but only to change the vote. Double voting is not allowed.
 

diff --git a/site/src/docs/manuals/separate-domain/index.md b/site/src/docs/manuals/separate-domain/index.md
@@ -10,7 +10,7 @@ Unless discussion [#1139](https://github.com/umputun/remark42/discussions/1139)
 
 ### 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.
+Set `ALLOWED_HOSTS='self',example1.org,example2.org` with your domain names and `AUTH_SAME_SITE=none`. The `'self'` value means "domain which Remark42 is installed on" so you don't need to write it twice.
 
 ### Technical details
 

diff --git a/site/src/docs/nav.json b/site/src/docs/nav.json
@@ -74,24 +74,20 @@
     "section": "Backup",
     "children": [
       {
-        "title": "Manual",
-        "href": "/backup/manual/"
-      },
-      {
-        "title": "Migration",
-        "href": "/backup/migration/"
+        "title": "Backup",
+        "href": "/backup/backup/"
       },
       {
         "title": "Restore",
         "href": "/backup/restore/"
       },
       {
-        "title": "Site URL migration",
-        "href": "/backup/url-migration/"
+        "title": "Migration",
+        "href": "/backup/migration/"
       },
       {
-        "title": "Automatic",
-        "href": "/backup/automatic/"
+        "title": "Site URL migration",
+        "href": "/backup/url-migration/"
       }
     ]
   },