refine hookshot role

docs/configuring-playbook-bridge-hookshot.md

@@ -10,7 +10,8 @@ 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.
-2. 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.
-3. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start bridging things.
+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.

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

@@ -13,28 +13,35 @@ matrix_hookshot_homeserver_address: "{{ matrix_homeserver_container_url }}"
 
 matrix_hookshot_public_endpoint: /hookshot
 
+# there is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
+matrix_hookshot_appservice_port: 9993
+matrix_hookshot_appservice_endpoint: "{{ matrix_hookshot_public_endpoint }}/_matrix/app"
+
 # metrics work only in conjunction with matrix_synapse_metrics_enabled etc
 matrix_hookshot_metrics_enabled: true
+# there is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
 matrix_hookshot_metrics_port: 9001
+matrix_hookshot_metrics_endpoint: "{{ matrix_hookshot_public_endpoint }}/metrics"
 
-matrix_hookshot_hookshot_port: 9993
+# there is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
 matrix_hookshot_webhook_port: 9000
+matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhooks"
 
 # you need to create a GitHub app to enable this
 # https://half-shot.github.io/matrix-hookshot/setup/github.html
-matrix_hookshot_github_enabled: true
-matrix_hookshot_github_appid: 123
+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: true
+matrix_hookshot_github_oauth_enabled: false
 matrix_hookshot_github_oauth_id: '' # "Client ID" on the GitHub App page
 matrix_hookshot_github_oauth_secret: '' # "Client Secret" on the GitHub App page
-matrix_hookshot_github_oauth_endpoint: "{{ matrix_hookshot_public_endpoint }}/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 }}"
-matrix_hookshot_github_ignore_hooks: '{}'
+matrix_hookshot_github_ignore_hooks: "{}"
 matrix_hookshot_github_command_prefix: '!gh'
 matrix_hookshot_github_show_issue_room_link: false
-matrix_hookshot_github_pr_diff: '{enabled: false, maxLines: 5}'
+matrix_hookshot_github_pr_diff: "{enabled: false, maxLines: 5}"
 matrix_hookshot_github_including_labels: ''
 matrix_hookshot_github_excluding_labels: ''
 
@@ -45,21 +52,37 @@ matrix_hookshot_gitlab_instances:
 
 matrix_hookshot_gitlab_secret: ''
 
-matrix_hookshot_jira_enabled: true
+matrix_hookshot_jira_enabled: false
 matrix_hookshot_jira_secret: ''
 matrix_hookshot_jira_oauth_id: ''
 matrix_hookshot_jira_oauth_secret: ''
-matrix_hookshot_jira_oauth_endpoint: "{{ matrix_hookshot_public_endpoint }}/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 }}"
 
 matrix_hookshot_generic_enabled: true
-matrix_hookshot_generic_endpoint: '{{ matrix_hookshot_public_endpoint }}/webhooks'
-matrix_hookshot_generic_urlprefix: '{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_generic_endpoint }}'
+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_provisioning_port: 9002
+matrix_hookshot_figma_enabled: false
+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:
+# matrix_hookshot_figma_instances:
+#   your-instance:
+#       teamId: your-team-id
+#       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: ''
+matrix_hookshot_provisioning_endpoint: "{{ matrix_hookshot_public_endpoint }}/v1"
+
+matrix_hookshot_bot_displayname: Hookshot Bot
+matrix_hookshot_bot_avatar: 'mxc://half-shot.uk/2876e89ccade4cb615e210c458e2a7a6883fe17d'
 
 # A list of extra arguments to pass to the container
 matrix_hookshot_container_extra_arguments: []
@@ -70,6 +93,17 @@ matrix_hookshot_systemd_required_services_list: ['docker.service']
 # List of systemd services that service wants
 matrix_hookshot_systemd_wanted_services_list: []
 
+# List of ports to bind to the host to expose them directly.
+# Ports will automatically be bound to localhost if matrix_nginx_proxy_enabled is false.
+# Setting this variable will override that behaviour in either case.
+# Supply docker port bind arguments in a list like this:
+#
+# matrix_hookshot_container_http_host_bind_ports:
+#   - "127.0.0.1:9999:{{ matrix_hookshot_metrics_port }}"
+#
+# Above example will bind the metrics port in the container to port 9999 on localhost.
+matrix_hookshot_container_http_host_bind_ports: []
+
 matrix_hookshot_appservice_token: ''
 matrix_hookshot_homeserver_token: ''
 

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

@@ -36,7 +36,8 @@
   - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
     set_fact:
       matrix_appservice_webhooks_matrix_nginx_proxy_configuration: |
-        location ~ ^{{ matrix_hookshot_public_endpoint }}/metrics$ {
+        {% 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;
@@ -52,31 +53,45 @@
             auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
           {% endif %}
         }
-        location ~ ^{{ matrix_hookshot_generic_endpoint }}/(.*)$ {
+        {% 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 #}
             resolver 127.0.0.11 valid=5s;
-            set $backend "matrix-hookshot:{{ matrix_hookshot_webhook_port }}";
+            set $backend "matrix-hookshot:{{ matrix_hookshot_appservice_port }}";
             proxy_pass http://$backend/$1;
           {% else %}
             {# Generic configuration for use outside of our container setup #}
-            proxy_pass http://127.0.0.1:{{ matrix_hookshot_webhook_port }}/$1;
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_appservice_port }}/$1;
           {% endif %}
           proxy_set_header Host $host;
         }
+        {% if matrix_hookshot_provisioning_enabled %}
+        location ~ ^{{ matrix_hookshot_provisioning_endpoint }}/(.*)$ {
           {% if matrix_nginx_proxy_enabled|default(False) %}
             {# Use the embedded DNS resolver in Docker containers to discover the service #}
-        location ~ ^{{ matrix_hookshot_public_endpoint }}/(.*)$ {
             resolver 127.0.0.11 valid=5s;
-          set $backend "matrix-hookshot:{{ matrix_hookshot_hookshot_port }}";
+            set $backend "matrix-hookshot:{{ matrix_hookshot_provisioning_port }}";
             proxy_pass http://$backend/$1;
-        }
           {% else %}
             {# Generic configuration for use outside of our container setup #}
-        location {{ matrix_hookshot_public_endpoint }}/ {
-          proxy_pass http://127.0.0.1:{{ matrix_hookshot_hookshot_port }}/;
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_provisioning_port }}/$1;
+          {% endif %}
+          proxy_set_header Host $host;
         }
         {% endif %}
+        location ~ ^{{ matrix_hookshot_webhook_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:{{ matrix_hookshot_webhook_port }}";
+            proxy_pass http://$backend/$1;
+          {% else %}
+            {# Generic configuration for use outside of our container setup #}
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_webhook_port }}/$1;
+          {% endif %}
+          proxy_set_header Host $host;
+        }
 
   - name: Register webhooks Appservice proxying configuration with matrix-nginx-proxy
     set_fact:

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

@@ -17,6 +17,27 @@
   with_items:
     - "{{ matrix_hookshot_base_path }}"
 
+# - name: Ensure openssl is installed (#1510)
+
+- name: Check if hookshot passkey exists
+  stat:
+    path: "{{ matrix_hookshot_data_path }}/passkey.pem"
+  register: hookshot_passkey_file
+
+- name: Generate hookshot passkey if it doesn't exist
+  shell: "{{ matrix_host_command_openssl }} genpkey -out {{ matrix_hookshot_base_path }}/passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:4096"
+  become: true
+  become_user: "{{ matrix_user_username }}"
+  when: "not hookshot_passkey_file.stat.exists"
+
+- name: Ensure hookshot config.yaml installed if provided
+  copy:
+    content: "{{ matrix_hookshot_config|to_nice_yaml }}"
+    dest: "{{ matrix_hookshot_base_path }}/config.yaml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
 - name: Ensure hookshot registration.yaml installed if provided
   copy:
     content: "{{ matrix_hookshot_registration|to_nice_yaml }}"

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

@@ -5,7 +5,7 @@ bridge:
   domain: {{ matrix_domain }}
   url: {{ matrix_hookshot_homeserver_address }}
   mediaUrl: { matrix_hookshot_homeserver_address }}
-  port: {{ matrix_hookshot_hookshot_port }}
+  port: {{ matrix_hookshot_appservice_port }}
   bindAddress: 0.0.0.0
 {% if matrix_hookshot_github_enabled %}
 github:
@@ -67,6 +67,13 @@ generic:
   allowJsTransformationFunctions: {{ matrix_hookshot_generic_allow_js_transformation_functions }}
   userIdPrefix: {{ matrix_hookshot_generic_user_id_prefix }}
 {% endif %}
+{% if matrix_hookshot_figma_enabled %}
+figma:
+  # (Optional) Configure this to enable Figma support
+  #
+  publicUrl: https://example.com/hookshot/
+  instances: {{ matrix_hookshot_figma_instances }}
+{% endif %}
 provisioning:
   # (Optional) Provisioning API for integration managers
   #
@@ -79,8 +86,8 @@ passFile:
 bot:
   # (Optional) Define profile information for the bot user
   #
-  displayname: GitHub Bot
-  avatar: mxc://half-shot.uk/2876e89ccade4cb615e210c458e2a7a6883fe17d
+  displayname: {{ matrix_hookshot_bot_displayname }}
+  avatar: {{ matrix_hookshot_bot_avatar }}
 metrics:
   # (Optional) Prometheus metrics support
   #
@@ -94,17 +101,20 @@ listeners:
   # Bind resource endpoints to ports and addresses.
   # 'resources' may be any of webhooks, widgets, metrics, provisioning, appservice
   #
+{# always enabled since all services need it #}
   - port: {{ matrix_hookshot_webhook_port }}
     bindAddress: 0.0.0.0
     resources:
       - webhooks
-      - widgets
+{% if matrix_hookshot_metrics_enabled %}
   - port: {{ matrix_hookshot_metrics_port }}
     bindAddress: 0.0.0.0
     resources:
       - metrics
-  - port: {{ matrix_hookshot_hookshot_port }}
+{% endif %}
+{% if matrix_hookshot_provisioning_enabled %}
+  - port: {{ matrix_hookshot_provisioning_port }}
     bindAddress: 0.0.0.0
     resources:
       - provisioning
-      - appservice
+{% endif %}

roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2

@@ -22,6 +22,9 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-hookshot \
           --cap-drop=ALL \
           --network={{ matrix_docker_network }} \
           -v {{ matrix_hookshot_base_path }}:/data:z \
+          {% for port in matrix_hookshot_container_http_host_bind_ports %}
+          -p {{ port }} \
+          {% endfor %}
           {% for arg in matrix_hookshot_container_extra_arguments %}
           {{ arg }} \
           {% endfor %}