diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index ee5213be9..f6adfda36 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/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 ` (where `` 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 `
` where you'd
```` -Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `` 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 @@ -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 +``` diff --git a/roles/custom/matrix-cactus-comments-client/defaults/main.yml b/roles/custom/matrix-cactus-comments-client/defaults/main.yml index 6a43ba585..7c5b15bfc 100644 --- a/roles/custom/matrix-cactus-comments-client/defaults/main.yml +++ b/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.