From 50f259d505008b388353df9583e61a4cf4d2f37f Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 27 Dec 2024 10:30:35 -0500 Subject: [PATCH 1/8] Update docs/configuring-playbook-cactus-comments.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index ee5213be9..679a0cea5 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -61,6 +61,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: From 909ca59cb7cee4f44670ce878dfca01ef3bc9581 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 02:49:37 +0900 Subject: [PATCH 2/8] Update docs/configuring-playbook-cactus-comments.md: remove the uncommon comment block Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 679a0cea5..77b6c54d2 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -25,10 +25,6 @@ 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 From 7f13747e82225418c3297f914484ce0667c09913 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 11:15:42 +0900 Subject: [PATCH 3/8] Update docs/configuring-playbook-cactus-comments.md: move the configuration enabled by default Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 77b6c54d2..4542fe11d 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -28,16 +28,15 @@ To enable Cactus Comments, add the following configuration to your `inventory/ho # 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 + # 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) From f2083aa8a7c62df1c6a1ae414a7d1e29d01dd769 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 02:51:19 +0900 Subject: [PATCH 4/8] Update docs/configuring-playbook-cactus-comments.md: replace the placeholders for the site name Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 4542fe11d..62dda0392 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -91,7 +91,7 @@ Upon starting Cactus Comments, a `bot.cactusbot` user account is created automat 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! @@ -105,7 +105,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 From 83ad4d4975a0c4bacd7997a4f2a3fc8b9918bca9 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 11:18:44 +0900 Subject: [PATCH 5/8] Update docs/configuring-playbook-cactus-comments.md: adopt the common instruction to start using the component Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 62dda0392..6dfdc4bd6 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -87,9 +87,7 @@ 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 get started, send `help` to the `@bot.cactusbot:example.com` bot to confirm it's working. +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). 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. From 89864c6de0e8592164fa23aba2de50003acbe86e Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 02:48:06 +0900 Subject: [PATCH 6/8] Update files for cactus-comments: add the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 15 +++++++++++++++ .../defaults/main.yml | 2 +- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 6dfdc4bd6..e6410946e 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -129,3 +129,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. From 1f532fe90d259acdf676171cce9defe14d2aae9f Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 11:40:28 +0900 Subject: [PATCH 7/8] Update docs/configuring-playbook-cactus-comments.md: add the configuration for changing the default username (bot.cactusbot) Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index e6410946e..3b6916d2f 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -32,6 +32,9 @@ matrix_cactus_comments_enabled: true # 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 ;) From abff629e366f484dabeab45026afee14f0681edd Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 11:42:10 +0900 Subject: [PATCH 8/8] Update docs/configuring-playbook-cactus-comments.md: replace "-" with "—" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-cactus-comments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 3b6916d2f..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).