Merge pull request #4000 from luixxiul/fix

Update files for Cactus Comments

docs/configuring-playbook-cactus-comments.md

@@ -8,9 +8,9 @@ See the project's [documentation](https://cactus.chat/docs/getting-started/intro
 
 The playbook contains 2 roles for configuring different pieces of the Cactus Comments system:
 
-- `matrix-cactus-comments` - the backend appservice integrating with the Matrix homeserver
+- `matrix-cactus-comments` — the backend appservice integrating with the Matrix homeserver
 
-- `matrix-cactus-comments-client` - a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
+- `matrix-cactus-comments-client` — a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
 
 You can enable whichever component you need (typically both).
 
@@ -25,23 +25,21 @@ If you wish to adjust it, see the section [below](#adjusting-the-cactus-comments
 To enable Cactus Comments, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-#################
-## Cactus Comments ##
-#################
-
 # This enables the backend (appservice)
 matrix_cactus_comments_enabled: true
 
+# This enables client assets static files serving on `https://matrix.example.com/cactus-comments`.
+# When the backend (appservice) is enabled, this is also enabled automatically, but we explicitly enable it here.
+matrix_cactus_comments_client_enabled: true
+
+# Uncomment and adjust this part if you'd like to use a username different than the default
+# matrix_cactus_comments_user_id: "bot.cactusbot"
+
 # To allow guest comments without users needing to log in, you need to have guest registration enabled.
 # To do this you need to uncomment one of the following lines (depending if you are using Synapse or Dendrite as a homeserver)
 # If you don't know which one you use: The default is Synapse ;)
 # matrix_synapse_allow_guest_access: true
 # matrix_dendrite_allow_guest_access: true
-
-# This enables client assets static files serving on `https://matrix.example.com/cactus-comments`.
-# When the backend (appservice) is enabled, this is also enabled automatically,
-# but we explicitly enable it here.
-matrix_cactus_comments_client_enabled: true
 ```
 
 ### Adjusting the Cactus Comments' client URL (optional)
@@ -61,6 +59,18 @@ If you've changed the default hostname, you may need to create a CNAME record fo
 
 When setting, replace `example.com` with your own.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the components.
+
+For `matrix-cactus-comments`, take a look at:
+
+- `roles/custom/matrix-cactus-comments/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+For `matrix-cactus-comments-client`, take a look at:
+
+- `roles/custom/matrix-cactus-comments-client/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
@@ -80,11 +90,9 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.
+To use the component, you need to start a chat with `@bot.cactusbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-To get started, send `help` to the `@bot.cactusbot:example.com` bot to confirm it's working.
-
-Then, register a site by sending `register <YourSiteName>` (where `<YourSiteName>` is a unique identifier you choose. It does not have to match your domain). You will then be invited into a moderation room.
+Then, register a site by sending `register YOUR_SITE_NAME_HERE` (where `YOUR_SITE_NAME_HERE` is a unique identifier you choose. It does not have to match your domain). You will then be invited into a moderation room.
 
 Now you are good to go and can embed the comment section on your website!
 
@@ -98,7 +106,7 @@ After including the JavaScript and CSS asset files, insert a `<div>` where you'd
 <div id="comment-section"></div>
 ````
 
-Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `<YourSiteName>` with the one that has been registered above:
+Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `YOUR_SITE_NAME_HERE` with the one that has been registered above:
 
 ```html
 <script>
@@ -106,7 +114,7 @@ initComments({
   node: document.getElementById("comment-section"),
   defaultHomeserverUrl: "https://matrix.example.com:8448",
   serverName: "example.com",
-  siteName: "<YourSiteName>",
+  siteName: "YOUR_SITE_NAME_HERE",
   commentSectionId: "1"
 })
 </script>
@@ -124,3 +132,18 @@ Make sure to replace `example.com` with your base domain before you include the
 ```
 
 **Note**: if the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_path_prefix` variables are tweaked, you would need to adjust the URLs of the assets accordingly.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-cactus-comments` for the backend appservice or `journalctl -fu matrix-cactus-comments-client` for the server serving the client assets, respectively.
+
+### Increase logging verbosity
+
+It is possible to increase logging verbosity for `matrix-cactus-comments-client`. The default logging level for this component is `error`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Controls the SERVER_LOG_LEVEL environment variable.
+# See: https://static-web-server.net/configuration/environment-variables/
+# Valid values: error, warn, info, debug, trace
+matrix_cactus_comments_client_environment_variable_server_log_level: debug
+```

roles/custom/matrix-cactus-comments-client/defaults/main.yml

@@ -67,7 +67,7 @@ matrix_cactus_comments_client_environment_variable_server_port: 8080
 
 # Controls the SERVER_LOG_LEVEL environment variable.
 # See: https://static-web-server.net/configuration/environment-variables/
-# Valid values: error, warn, info, debug or trace
+# Valid values: error, warn, info, debug, trace
 matrix_cactus_comments_client_environment_variable_server_log_level: error
 
 # Controls the SERVER_LOG_REMOTE_ADDRESS environment variable.