refine hookshot role

docs/configuring-playbook-bridge-hookshot.md

@@ -9,9 +9,13 @@ See the project's [documentation](https://half-shot.github.io/matrix-hookshot/ho
 
 Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/setup.html) to learn what the individual options do.
 
-1. For each of the services (GitHub, GitLab, JIRA, generic webhooks) fill in the respected variables `matrix_hookshot_service_*` listed in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) as required.
+1. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) as required.
 2. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
 3. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
 4. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
 
-Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` variable.
+The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
+
+If metrics are enabled, they will be automatically available in the builtin Prometheus and Grafana, but you need to set up your own Dashboard for now. If additionally metrics proxying for use with external Prometheus is enabled (`matrix_nginx_proxy_proxy_synapse_metrics`), hookshot metrics will also be available (at `matrix_hookshot_metrics_endpoint`, default `/hookshot/metrics`, on the stats subdomain). See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).
+
+Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in `/roles/matrix-bridge-hookshot/defaults/main.yml` for how to use them.

group_vars/matrix_servers

@@ -673,6 +673,8 @@ matrix_hookshot_container_http_host_bind_ports_defaultmapping:
 
 matrix_hookshot_container_http_host_bind_ports: matrix_hookshot_container_http_host_bind_ports_defaultmapping if matrix_nginx_proxy_enabled else []
 
+matrix_hookshot_provisioning_enabled: "{{ true if matrix_hookshot_provisioning_secret and matrix_dimension_enabled else false}}"
+
 ######################################################################
 #
 # /matrix-bridge-hookshot

roles/matrix-bridge-hookshot/defaults/main.yml

@@ -28,17 +28,21 @@ matrix_hookshot_metrics_endpoint: "{{ matrix_hookshot_public_endpoint }}/metrics
 matrix_hookshot_webhook_port: 9000
 matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhooks"
 
-# you need to create a GitHub app to enable this
+
+# you need to create a GitHub app to enable this and fill in the empty variables below
 # https://half-shot.github.io/matrix-hookshot/setup/github.html
 matrix_hookshot_github_enabled: false
 matrix_hookshot_github_appid: ''
 matrix_hookshot_github_private_key: ''
 matrix_hookshot_github_secret: '' # "Webhook secret" on the GitHub App page
 matrix_hookshot_github_oauth_enabled: false
+# you need to configure oauth settings only when you have enabled oauth (optional)
 matrix_hookshot_github_oauth_id: '' # "Client ID" on the GitHub App page
 matrix_hookshot_github_oauth_secret: '' # "Client Secret" on the GitHub App page
+# default value of matrix_hookshot_github_oauth_endpoint: "/hookshot/webhooks/oauth"
 matrix_hookshot_github_oauth_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/oauth"
 matrix_hookshot_github_oauth_uri: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_github_oauth_endpoint }}"
+# these are the default settings mentioned here and don't need to be modified: https://half-shot.github.io/matrix-hookshot/usage/room_configuration/github_repo.html#configuration
 matrix_hookshot_github_ignore_hooks: "{}"
 matrix_hookshot_github_command_prefix: '!gh'
 matrix_hookshot_github_show_issue_room_link: false
@@ -46,27 +50,44 @@ matrix_hookshot_github_pr_diff: "{enabled: false, maxLines: 5}"
 matrix_hookshot_github_including_labels: ''
 matrix_hookshot_github_excluding_labels: ''
 
+
 matrix_hookshot_gitlab_enabled: true
+# optionally add your instances, e.g.
+# matrix_hookshot_gitlab_instances:
+#   gitlab.com:
+#     url: https://gitlab.com
+#   mygitlab:
+#     url: https://gitlab.example.org
 matrix_hookshot_gitlab_instances:
   gitlab.com:
     url: https://gitlab.com
 
+# this will be the "Secret token" you have to enter into all GitLab instances for authentication
 matrix_hookshot_gitlab_secret: ''
 
+
 matrix_hookshot_jira_enabled: false
+# get the these values from https://half-shot.github.io/matrix-hookshot/setup/jira.html#jira-oauth
 matrix_hookshot_jira_secret: ''
+matrix_hookshot_jira_oauth_enabled: false
 matrix_hookshot_jira_oauth_id: ''
 matrix_hookshot_jira_oauth_secret: ''
+# default value of matrix_hookshot_jira_oauth_endpoint: "/hookshot/webhooks/jira/oauth"
 matrix_hookshot_jira_oauth_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/jira/oauth"
 matrix_hookshot_jira_oauth_uri: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_jira_oauth_endpoint }}"
 
+
+# no need to change these
 matrix_hookshot_generic_enabled: true
+# default value of matrix_hookshot_generic_endpoint: "/hookshot/webhooks"
 matrix_hookshot_generic_endpoint: "{{ matrix_hookshot_webhook_endpoint }}"
 matrix_hookshot_generic_urlprefix: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_generic_endpoint }}"
 matrix_hookshot_generic_allow_js_transformation_functions: false
 matrix_hookshot_generic_user_id_prefix: 'webhooks_'
 
+
 matrix_hookshot_figma_enabled: false
+# default value of matrix_hookshot_figma_endpoint: "/hookshot/webhooks/figma/webhook"
 matrix_hookshot_figma_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/figma/webhook"
 matrix_hookshot_figma_publicUrl: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_figma_endpoint }}"
 # to bridge figma webhooks, you need to configure one of multiple instances like this:
@@ -76,12 +97,15 @@ matrix_hookshot_figma_publicUrl: "{{ matrix_server_fqn_matrix }}{{ matrix_hooksh
 #       accessToken: your-personal-access-token
 #       passcode: your-webhook-passcode
 
-matrix_hookshot_provisioning_enabled: true
+
 # there is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
 matrix_hookshot_provisioning_port: 9002
 matrix_hookshot_provisioning_secret: ''
+# provisioning will be automatically enabled if dimension is enabled and you have provided a provisioning secret, unless you override it
+matrix_hookshot_provisioning_enabled: false
 matrix_hookshot_provisioning_endpoint: "{{ matrix_hookshot_public_endpoint }}/v1"
 
+
 matrix_hookshot_bot_displayname: Hookshot Bot
 matrix_hookshot_bot_avatar: 'mxc://half-shot.uk/2876e89ccade4cb615e210c458e2a7a6883fe17d'
 

roles/matrix-bridge-hookshot/tasks/init.yml

@@ -36,24 +36,6 @@
   - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
     set_fact:
       matrix_hookshot_matrix_nginx_proxy_configuration: |
-        {% if matrix_hookshot_metrics_enabled %}
-        location {{ matrix_hookshot_metrics_endpoint }} {
-          {% if matrix_nginx_proxy_enabled|default(False) %}
-            {# Use the embedded DNS resolver in Docker containers to discover the service #}
-            resolver 127.0.0.11 valid=5s;
-            set $backend "{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_metrics_port }}";
-            proxy_pass http://$backend/metrics;
-          {% else %}
-            {# Generic configuration for use outside of our container setup #}
-            proxy_pass http://127.0.0.1:{{ matrix_hookshot_metrics_port }}/metrics;
-          {% endif %}
-          proxy_set_header Host $host;
-          {% if matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled %}
-            auth_basic "protected";
-            auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
-          {% endif %}
-        }
-        {% endif %}
         location ~ ^{{ matrix_hookshot_appservice_endpoint }}/(.*)$ {
           {% if matrix_nginx_proxy_enabled|default(False) %}
             {# Use the embedded DNS resolver in Docker containers to discover the service #}
@@ -101,6 +83,37 @@
           +
           [matrix_hookshot_matrix_nginx_proxy_configuration]
         }}
+
+  - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
+    set_fact:
+      matrix_hookshot_matrix_nginx_proxy_metrics_configuration: |
+        {% if matrix_hookshot_metrics_enabled %}
+        location {{ matrix_hookshot_metrics_endpoint }} {
+          {% if matrix_nginx_proxy_enabled|default(False) %}
+            {# Use the embedded DNS resolver in Docker containers to discover the service #}
+            resolver 127.0.0.11 valid=5s;
+            set $backend "{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_metrics_port }}";
+            proxy_pass http://$backend/metrics;
+          {% else %}
+            {# Generic configuration for use outside of our container setup #}
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_metrics_port }}/metrics;
+          {% endif %}
+          proxy_set_header Host $host;
+          {% if matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled %}
+            auth_basic "protected";
+            auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
+          {% endif %}
+        }
+        {% endif %}
+
+  - name: Register hookshot metrics proxying configuration with matrix-nginx-proxy
+    set_fact:
+      matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks: |
+        {{
+          matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks|default([])
+          +
+          [matrix_hookshot_matrix_nginx_proxy_metrics_configuration]
+        }}
   tags:
    - always
   when: matrix_hookshot_enabled|bool

roles/matrix-bridge-hookshot/tasks/setup_install.yml

@@ -1,5 +1,8 @@
 ---
 
+#  (#1510)
+# - import_tasks: "{{ role_path }}/../matrix-base/tasks/util/ensure_openssl_installed.yml"
+
 - name: Ensure hookshot image is pulled
   docker_image:
     name: "{{ matrix_hookshot_docker_image }}"
@@ -17,8 +20,6 @@
   with_items:
     - "{{ matrix_hookshot_base_path }}"
 
-# - name: Ensure openssl is installed (#1510)
-
 - name: Check if hookshot passkey exists
   stat:
     path: "{{ matrix_hookshot_base_path }}/passkey.pem"

roles/matrix-bridge-hookshot/templates/config.yml.j2

@@ -53,11 +53,13 @@ jira:
   #
   webhook:
     secret: {{ matrix_hookshot_jira_secret }}
+{% if matrix_hookshot_jira_oauth_enabled %}
   oauth:
     client_id: {{ matrix_hookshot_jira_oauth_id }}
     client_secret: {{ matrix_hookshot_jira_oauth_secret }}
     redirect_uri: {{ matrix_hookshot_jira_oauth_uri }}
 {% endif %}
+{% endif %}
 {% if matrix_hookshot_generic_enabled %}
 generic:
   # (Optional) Support for generic webhook events. `allowJsTransformationFunctions` will allow users to write short transformation snippets in code, and thus is unsafe in untrusted environments
@@ -74,10 +76,12 @@ figma:
   publicUrl: https://example.com/hookshot/
   instances: {{ matrix_hookshot_figma_instances }}
 {% endif %}
+{% if matrix_hookshot_provisioning_enabled %}
 provisioning:
   # (Optional) Provisioning API for integration managers
   #
   secret: {{ matrix_hookshot_provisioning_secret }}
+{% endif %}
 passFile:
   # A passkey used to encrypt tokens stored inside the bridge.
   # Run openssl genpkey -out passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:4096 to generate