Add gomuks as optional alternative web client

Add new role custom/matrix-client-gomuks for https://github.com/gomuks/gomuks
(web frontend with Go bouncer backend, image dock.mau.dev/gomuks/gomuks).

The client is disabled by default (matrix_client_gomuks_enabled: false)
so Element remains the default web client and the change is safe to
push upstream.

Configuration is derived from ~/.config/containers/systemd/gomuks.container
but adapted for the playbook: single /data bind mount (GOMUKS_ROOT=/data),
listens on 0.0.0.0:29325, Traefik labels, systemd service, and
generation of config.yaml from matrix_homeserver_generic_secret_key
(auth, token_key, VAPID keys, origin_patterns, logging).

Wiring: matrix_server_fqn_gomuks, group_vars, setup.yml,
matrix_playbook_public_client_urls, systemd manager; docs,
container-images and README updated.

README.md

@@ -69,6 +69,7 @@ Web clients for Matrix that you can host on your own domains.
 | [SchildiChat Web](https://schildi.chat/) | ❌ | Based on Element Web, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat-web.md) |
 | [FluffyChat Web](https://fluffychat.im/) | ❌ | The cutest messenger in Matrix | [Link](docs/configuring-playbook-client-fluffychat-web.md) |
 | [Commet](https://github.com/commetchat/commet) | ❌ | Matrix web client | [Link](docs/configuring-playbook-client-commet.md) |
+| [gomuks](https://github.com/gomuks/gomuks) | ❌ | Bouncer-style Matrix client with web frontend | [Link](docs/configuring-playbook-client-gomuks.md) |
 
 ### Server Components
 

docs/configuring-playbook-client-gomuks.md

@@ -0,0 +1,133 @@
+<!--
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up gomuks (optional)
+
+The playbook can install and configure [gomuks](https://github.com/gomuks/gomuks) for you.
+
+gomuks is a Matrix client written in Go. The `gomuks` container in this playbook runs the gomuks backend which serves the web frontend. It acts as a bouncer — keeping your encryption keys and syncing in the background, even when the browser is closed. See the project's [documentation](https://docs.mau.fi/gomuks/) to learn what it does and why it might be useful to you.
+
+By default, this playbook does not install gomuks. Element Web remains the default client.
+
+## Adjusting DNS records
+
+By default, this playbook installs gomuks on the `gomuks.` subdomain (`gomuks.example.com`) and requires you to create a CNAME record for `gomuks`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+## Adjusting the playbook configuration
+
+To enable gomuks, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_client_gomuks_enabled: true
+```
+
+### Adjusting the gomuks URL (optional)
+
+By tweaking the `matrix_client_gomuks_hostname` and `matrix_client_gomuks_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for gomuks.
+matrix_client_gomuks_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /gomuks subpath
+matrix_client_gomuks_path_prefix: /gomuks
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the gomuks domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+**Note**: `matrix_client_gomuks_path_prefix` must either be `/` or not end with a slash (e.g. `/gomuks`).
+
+### Adjusting authentication (optional)
+
+gomuks protects its web interface with a basic-auth username and password (separate from your Matrix account). The playbook auto-generates these from `matrix_homeserver_generic_secret_key`:
+
+- `matrix_client_gomuks_auth_username` — defaults to `gomuks`
+- `matrix_client_gomuks_auth_password` — auto-generated, truncated hash of the secret key
+
+To set your own credentials, add the following to your `vars.yml`:
+
+```yaml
+matrix_client_gomuks_auth_username: "myuser"
+matrix_client_gomuks_auth_password: "mysupersecretpassword"
+```
+
+The playbook derives a bcrypt hash automatically. You can also set the hash directly:
+
+```yaml
+matrix_client_gomuks_auth_password_hash: "$2a$12$..."
+```
+
+If your gomuks instance is behind an authenticating reverse proxy and you prefer to handle auth there, you can disable gomuks' own auth:
+
+```yaml
+matrix_client_gomuks_disable_auth: true
+```
+
+When disabling auth, be careful not to expose gomuks to untrusted networks. See the [gomuks FAQ](https://docs.mau.fi/gomuks/faq.html#can-i-run-the-backend-behind-a-reverse-proxy) for details.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-gomuks/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-gomuks/templates/config.yaml.j2` for the component's default runtime configuration. gomuks stores additional settings (like VAPID keys, `token_key`, etc.) in `/data/config/config.yaml`; the playbook generates them from your `matrix_homeserver_generic_secret_key` so that they remain stable across restarts
+
+Additional useful variables include:
+
+- `matrix_client_gomuks_container_image` — override the container image
+- `matrix_client_gomuks_web_listen_address` — listen address inside the container
+- `matrix_client_gomuks_origin_patterns` — allowed `Origin` header patterns
+- `matrix_client_gomuks_insecure_cookies` — allow cookies over plain HTTP (useful without TLS, not recommended)
+
+## 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:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Usage
+
+After installation, gomuks will be available at `https://gomuks.example.com` (or your custom hostname/path).
+
+1. Open the URL in your browser.
+2. You will be prompted for the gomuks basic-auth credentials (see [Adjusting authentication](#adjusting-authentication-optional)). This is **not** your Matrix password — it's the bouncer protection.
+3. Log in with your Matrix account (user ID, password, homeserver).
+
+Your encryption keys stay on the server's `/matrix/client-gomuks/data` directory, so the backend keeps syncing even when no browser is open.
+
+All gomuks data (config, database, logs) lives under `{{ matrix_client_gomuks_data_path }}` (`/matrix/client-gomuks` by default) on the server.
+
+## 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-client-gomuks`.
+
+If you changed `matrix_client_gomuks_auth_password` and cannot log in, note that the browser may have cached the old basic-auth credentials — try a private window or clear site data.
+
+If you see errors about `origin_patterns`, verify that `matrix_client_gomuks_hostname` and `matrix_client_gomuks_origin_patterns` include the hostname you are using to access gomuks (without `https://` and with explicit port if non-standard).
+
+To reset gomuks completely (removes database and forces re-login), stop the service and remove its data directory, then re-run the playbook:
+
+```sh
+systemctl stop matrix-client-gomuks
+rm -rf /matrix/client-gomuks/data/*
+# then re-run: just setup-all --tags=setup-client-gomuks
+```

docs/configuring-playbook.md

@@ -97,6 +97,8 @@ Web clients for Matrix that you can host on your own domains.
 
 - [Setting up Commet](configuring-playbook-client-commet.md), if you've enabled [Commet](https://github.com/commetchat/commet), a Matrix web client
 
+- [Setting up gomuks](configuring-playbook-client-gomuks.md), if you've enabled [gomuks](https://github.com/gomuks/gomuks), a bouncer-style Matrix client with a web frontend
+
 
 ### Authentication and user-related
 

docs/container-images.md

@@ -42,6 +42,7 @@ Web clients for Matrix that you can host on your own domains.
 | [Cinny](configuring-playbook-client-cinny.md) | [ajbura/cinny](https://hub.docker.com/r/ajbura/cinny) | ❌ | Simple, elegant and secure web client |
 | [Sable](configuring-playbook-client-sable.md) | [7w1/sable](https://ghcr.io/7w1/sable) | ❌ | Simple, elegant and secure web client |
 | [SchildiChat Web](configuring-playbook-client-schildichat-web.md) | [etke.cc/schildichat-web](https://ghcr.io/etkecc/schildichat-web) | ❌ | Based on Element Web, with a more traditional instant messaging experience |
+| [gomuks](configuring-playbook-client-gomuks.md) | [gomuks/gomuks](https://mau.dev/gomuks/gomuks/container_registry) | ❌ | Bouncer-style Matrix client with Go backend and web frontend |
 
 ## Server Components
 

group_vars/matrix_servers

@@ -66,6 +66,8 @@ matrix_playbook_public_client_urls: |
   {{
     ([matrix_client_element_scheme + '://' + matrix_client_element_hostname + matrix_client_element_path_prefix] if matrix_client_element_enabled else [])
     +
+    ([matrix_client_gomuks_scheme + '://' + matrix_client_gomuks_hostname + matrix_client_gomuks_path_prefix] if matrix_client_gomuks_enabled else [])
+    +
     ([matrix_client_commet_scheme + '://' + matrix_client_commet_hostname + matrix_client_commet_path_prefix] if matrix_client_commet_enabled else [])
     +
     ([hydrogen_scheme + '://' + hydrogen_hostname + hydrogen_path_prefix] if hydrogen_enabled else [])
@@ -666,6 +668,13 @@ devture_systemd_service_manager_services_list_auto: |
       'groups': ['matrix', 'clients', 'commet', 'client-commet'],
     }] if matrix_client_commet_enabled else [])
     +
+    ([{
+      'name': 'matrix-client-gomuks.service',
+      'priority': 2000,
+      'restart_necessary': (matrix_client_gomuks_restart_necessary | bool),
+      'groups': ['matrix', 'clients', 'gomuks', 'client-gomuks'],
+    }] if matrix_client_gomuks_enabled else [])
+    +
     ([{
       'name': 'matrix-client-fluffychat.service',
       'priority': 2000,
@@ -4773,6 +4782,38 @@ matrix_client_commet_container_labels_traefik_compression_middleware_name: "{{ m
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-client-gomuks
+#
+######################################################################
+
+matrix_client_gomuks_enabled: false
+
+matrix_client_gomuks_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
+
+matrix_client_gomuks_hostname: "gomuks.{{ matrix_domain }}"
+
+matrix_client_gomuks_container_http_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '29325') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
+
+matrix_client_gomuks_container_network: "{{ matrix_addons_container_network }}"
+
+matrix_client_gomuks_container_additional_networks: "{{ [matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_client_gomuks_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [] }}"
+
+matrix_client_gomuks_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_client_gomuks_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_client_gomuks_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+matrix_client_gomuks_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+matrix_client_gomuks_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_client_gomuks_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"
+
+######################################################################
+#
+# /matrix-client-gomuks
+#
+######################################################################
+
 ######################################################################
 #
 # hydrogen

roles/custom/matrix-base/defaults/main.yml

@@ -134,6 +134,9 @@ matrix_server_fqn_schildichat: "schildichat.{{ matrix_domain }}"
 # This is where you access the FluffyChat Web from (if enabled via matrix_client_fluffychat_enabled; disabled by default).
 matrix_server_fqn_fluffychat: "fluffychat.{{ matrix_domain }}"
 
+# This is where you access the gomuks web client from (if enabled via matrix_client_gomuks_enabled; disabled by default).
+matrix_server_fqn_gomuks: "gomuks.{{ matrix_domain }}"
+
 # This is where you access the Buscarron bot from (if enabled via matrix_bot_buscarron_enabled; disabled by default).
 matrix_server_fqn_buscarron: "buscarron.{{ matrix_domain }}"
 

roles/custom/matrix-client-gomuks/defaults/main.yml

@@ -0,0 +1,209 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+# Project source code URL: https://github.com/gomuks/gomuks
+
+matrix_client_gomuks_enabled: false
+
+# renovate: datasource=docker depName=dock.mau.dev/gomuks/gomuks
+matrix_client_gomuks_version: latest
+
+matrix_client_gomuks_container_image: "{{ matrix_client_gomuks_container_image_registry_prefix }}gomuks/gomuks:{{ matrix_client_gomuks_version }}"
+matrix_client_gomuks_container_image_registry_prefix: "{{ matrix_client_gomuks_container_image_registry_prefix_upstream }}"
+matrix_client_gomuks_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_client_gomuks_container_image_registry_prefix_upstream_default }}"
+matrix_client_gomuks_container_image_registry_prefix_upstream_default: dock.mau.dev/
+
+matrix_client_gomuks_data_path: "{{ matrix_base_data_path }}/client-gomuks"
+
+# The base container network
+matrix_client_gomuks_container_network: ''
+
+# A list of additional container networks that the container would be connected to.
+# The role does not create these networks, so make sure they already exist.
+# Use this to expose this container to a reverse proxy, which runs in a different container network.
+matrix_client_gomuks_container_additional_networks: []
+
+# The in-container port that gomuks listens on.
+matrix_client_gomuks_container_port: 29325
+
+# Controls whether the matrix-client-gomuks container exposes its HTTP port (tcp/29325 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:29325"), or empty string to not expose.
+matrix_client_gomuks_container_http_host_bind_port: ''
+
+# matrix_client_gomuks_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
+# See `../templates/labels.j2` for details.
+#
+# To inject your own other container labels, see `matrix_client_gomuks_container_labels_additional_labels`.
+matrix_client_gomuks_container_labels_traefik_enabled: true
+matrix_client_gomuks_container_labels_traefik_docker_network: "{{ matrix_client_gomuks_container_network }}"
+matrix_client_gomuks_container_labels_traefik_hostname: "{{ matrix_client_gomuks_hostname }}"
+# The path prefix must either be `/` or not end with a slash (e.g. `/gomuks`).
+matrix_client_gomuks_container_labels_traefik_path_prefix: "{{ matrix_client_gomuks_path_prefix }}"
+matrix_client_gomuks_container_labels_traefik_rule: "Host(`{{ matrix_client_gomuks_container_labels_traefik_hostname }}`){% if matrix_client_gomuks_container_labels_traefik_path_prefix != '/' %} && PathPrefix(`{{ matrix_client_gomuks_container_labels_traefik_path_prefix }}`){% endif %}"
+matrix_client_gomuks_container_labels_traefik_priority: 0
+matrix_client_gomuks_container_labels_traefik_entrypoints: web-secure
+matrix_client_gomuks_container_labels_traefik_tls: "{{ matrix_client_gomuks_container_labels_traefik_entrypoints != 'web' }}"
+matrix_client_gomuks_container_labels_traefik_tls_certResolver: default  # noqa var-naming
+
+# Controls whether a compression middleware will be injected into the middlewares list.
+# This compression middleware is supposed to be defined elsewhere (using labels or a File provider, etc.) and is merely referenced by this router.
+matrix_client_gomuks_container_labels_traefik_compression_middleware_enabled: false
+matrix_client_gomuks_container_labels_traefik_compression_middleware_name: ""
+
+# Controls which additional headers to attach to all HTTP responses.
+# To add your own headers, use `matrix_client_gomuks_container_labels_traefik_additional_response_headers_custom`
+matrix_client_gomuks_container_labels_traefik_additional_response_headers: "{{ matrix_client_gomuks_container_labels_traefik_additional_response_headers_auto | combine(matrix_client_gomuks_container_labels_traefik_additional_response_headers_custom) }}"
+matrix_client_gomuks_container_labels_traefik_additional_response_headers_auto: |
+  {{
+    {}
+    | combine ({'X-Frame-Options': matrix_client_gomuks_http_header_x_frame_options} if matrix_client_gomuks_http_header_x_frame_options else {})
+    | combine ({'X-XSS-Protection': matrix_client_gomuks_http_header_xss_protection} if matrix_client_gomuks_http_header_xss_protection else {})
+    | combine ({'X-Content-Type-Options': matrix_client_gomuks_http_header_content_type_options} if matrix_client_gomuks_http_header_content_type_options else {})
+    | combine ({'Content-Security-Policy': matrix_client_gomuks_http_header_content_security_policy} if matrix_client_gomuks_http_header_content_security_policy else {})
+    | combine ({'Permission-Policy': matrix_client_gomuks_http_header_content_permission_policy} if matrix_client_gomuks_http_header_content_permission_policy else {})
+    | combine ({'Strict-Transport-Security': matrix_client_gomuks_http_header_strict_transport_security} if matrix_client_gomuks_http_header_strict_transport_security and matrix_client_gomuks_container_labels_traefik_tls else {})
+  }}
+matrix_client_gomuks_container_labels_traefik_additional_response_headers_custom: {}
+
+# matrix_client_gomuks_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
+# See `../templates/labels.j2` for details.
+#
+# Example:
+# matrix_client_gomuks_container_labels_additional_labels: |
+#   my.label=1
+#   another.label="here"
+matrix_client_gomuks_container_labels_additional_labels: ''
+
+# A list of extra arguments to pass to the container
+matrix_client_gomuks_container_extra_arguments: []
+
+# List of systemd services that matrix-client-gomuks.service depends on
+matrix_client_gomuks_systemd_required_services_list: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
+
+# Specifies the value of the `X-Frame-Options` header.
+matrix_client_gomuks_http_header_x_frame_options: SAMEORIGIN
+
+# Specifies the value of the `X-XSS-Protection` header
+matrix_client_gomuks_http_header_xss_protection: "1; mode=block"
+
+# Specifies the value of the `X-Content-Type-Options` header.
+matrix_client_gomuks_http_header_content_type_options: nosniff
+
+# Specifies the value of the `Content-Security-Policy` header.
+matrix_client_gomuks_http_header_content_security_policy: frame-ancestors 'self'
+
+# Specifies the value of the `Permission-Policy` header.
+matrix_client_gomuks_http_header_content_permission_policy: "{{ 'interest-cohort=()' if matrix_client_gomuks_floc_optout_enabled else '' }}"
+
+# Specifies the value of the `Strict-Transport-Security` header.
+matrix_client_gomuks_http_header_strict_transport_security: "max-age=31536000; includeSubDomains{{ '; preload' if matrix_client_gomuks_hsts_preload_enabled else '' }}"
+
+# Controls whether to send a "Permissions-Policy interest-cohort=();" header along with all responses
+matrix_client_gomuks_floc_optout_enabled: true
+
+# Controls if HSTS preloading is enabled
+matrix_client_gomuks_hsts_preload_enabled: false
+
+matrix_client_gomuks_scheme: https
+# The hostname at which gomuks is served.
+matrix_client_gomuks_hostname: "{{ matrix_server_fqn_gomuks }}"
+
+# The path at which gomuks is exposed.
+# This value must either be `/` or not end with a slash (e.g. `/gomuks`).
+matrix_client_gomuks_path_prefix: /
+
+# Controls whether the self-check feature should validate SSL certificates.
+matrix_client_gomuks_self_check_validate_certificates: true
+
+# Gomuks web server configuration.
+# See https://github.com/gomuks/gomuks/blob/main/pkg/gomuks/config.go for details.
+
+# The address the gomuks web server listens on inside the container.
+matrix_client_gomuks_web_listen_address: "0.0.0.0:{{ matrix_client_gomuks_container_port }}"
+
+# Username for the gomuks web basic auth (NOT your Matrix account).
+# Leave empty to let the playbook generate one from matrix_homeserver_generic_secret_key,
+# or set to your preferred username.
+matrix_client_gomuks_auth_username: "{{ 'gomuks' }}"
+
+# Password for the gomuks web basic auth (NOT your Matrix account).
+# Leave empty to auto-generate from matrix_homeserver_generic_secret_key.
+# This is the plaintext password the user will enter in the browser.
+# The playbook will derive a bcrypt hash from it for the config file.
+matrix_client_gomuks_auth_password: "{{ (matrix_homeserver_generic_secret_key + ':gomuks.auth_password') | hash('sha512') | truncate(24, True, '') }}"
+
+# Salt used for deterministic bcrypt hashing of the above password.
+# Changing this will change the derived password hash and trigger a restart.
+matrix_client_gomuks_auth_password_salt: "{{ (matrix_homeserver_generic_secret_key + ':gomuks.password_salt') | hash('sha512') | truncate(22, True, '') }}"
+
+# Bcrypt hash of the password. The role computes it from the plaintext password and salt.
+# You can override this directly if you wish to provide your own hash.
+matrix_client_gomuks_auth_password_hash: "{{ matrix_client_gomuks_auth_password | password_hash('bcrypt', matrix_client_gomuks_auth_password_salt) }}"
+
+# Token key used for signing auth tokens. Auto-generated from the generic secret key.
+matrix_client_gomuks_token_key: "{{ (matrix_homeserver_generic_secret_key + ':gomuks.token_key') | hash('sha512') | b64encode | truncate(64, True, '') | regex_replace('[^A-Za-z0-9]', 'A') }}"
+
+# Whether to disable authentication entirely.
+# If true, the web UI will be accessible without username/password.
+# Useful if you put authentication in the reverse proxy.
+# See https://github.com/gomuks/gomuks/blob/main/pkg/gomuks/config.go#L70
+matrix_client_gomuks_disable_auth: false
+
+# Controls whether gomuks allows insecure (non-HTTPS) cookies.
+matrix_client_gomuks_insecure_cookies: false
+
+# The origin patterns gomuks will allow. By default, it allows all hosts matching its public hostname and localhost.
+matrix_client_gomuks_origin_patterns: |
+  {{
+    [matrix_client_gomuks_hostname] + ['localhost:*', '*.localhost:*']
+    if matrix_client_gomuks_hostname else ['localhost:*', '*.localhost:*']
+  }}
+
+# Whether to enable debug endpoints.
+matrix_client_gomuks_debug_endpoints: false
+
+# Size of the websocket event buffer.
+matrix_client_gomuks_event_buffer_size: 512
+
+# Matrix configuration.
+matrix_client_gomuks_matrix_disable_http2: false
+matrix_client_gomuks_matrix_set_presence: offline
+
+# Media configuration.
+matrix_client_gomuks_media_thumbnail_size: 120
+
+# Push / VAPID configuration.
+matrix_client_gomuks_push_fcm_gateway: "https://push.gomuks.app"
+matrix_client_gomuks_push_vapid_private_key: "{{ (matrix_homeserver_generic_secret_key + ':gomuks.vapid_private') | hash('sha512') | b64encode | truncate(43, True, '') | regex_replace('[^A-Za-z0-9_-]', 'A') }}"
+matrix_client_gomuks_push_vapid_public_key: "{{ (matrix_homeserver_generic_secret_key + ':gomuks.vapid_public') | hash('sha512') | b64encode | truncate(87, True, '') | regex_replace('[^A-Za-z0-9_-]', 'B') }}"
+
+# Logging configuration.
+matrix_client_gomuks_logging_min_level: info
+matrix_client_gomuks_logging_writers: |
+  {{
+    [
+      {
+        'type': 'stdout',
+        'format': 'pretty-colored',
+      },
+      {
+        'type': 'file',
+        'format': 'json',
+        'filename': '/data/logs/gomuks.log',
+        'max_size': 100,
+        'max_backups': 10,
+      }
+    ]
+  }}
+
+# Additional environment variables to pass to the container.
+matrix_client_gomuks_environment_variables_extension: ''
+
+# matrix_client_gomuks_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+matrix_client_gomuks_restart_necessary: false

roles/custom/matrix-client-gomuks/tasks/main.yml

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- tags:
+    - setup-all
+    - setup-client-gomuks
+    - install-all
+    - install-client-gomuks
+  block:
+    - when: matrix_client_gomuks_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
+    - when: matrix_client_gomuks_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
+
+- tags:
+    - setup-all
+    - setup-client-gomuks
+  block:
+    - when: not matrix_client_gomuks_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+
+- tags:
+    - self-check
+  block:
+    - when: matrix_client_gomuks_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/self_check.yml"

roles/custom/matrix-client-gomuks/tasks/self_check.yml

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check gomuks
+  ansible.builtin.uri:
+    url: "{{ matrix_client_gomuks_scheme }}://{{ matrix_client_gomuks_hostname }}{{ matrix_client_gomuks_path_prefix | regex_replace('/$', '') }}/"
+    follow_redirects: none
+    validate_certs: "{{ matrix_client_gomuks_self_check_validate_certificates }}"
+  check_mode: false
+  register: matrix_client_gomuks_self_check_result
+  ignore_errors: true
+  delegate_to: 127.0.0.1
+  become: false
+
+- name: Fail if gomuks self-check fails
+  ansible.builtin.fail:
+    msg: "Failed checking gomuks is up at `{{ matrix_client_gomuks_scheme }}://{{ matrix_client_gomuks_hostname }}{{ matrix_client_gomuks_path_prefix }}` (checked `{{ matrix_client_gomuks_scheme }}://{{ matrix_client_gomuks_hostname }}{{ matrix_client_gomuks_path_prefix | regex_replace('/$', '') }}/`). Is gomuks running? Is the hostname correct? Is Trafiek forwarding correctly? ({{ matrix_client_gomuks_self_check_result.msg }})"
+  when: "matrix_client_gomuks_self_check_result.failed | default(false) or matrix_client_gomuks_self_check_result.status not in [200, 302]"

roles/custom/matrix-client-gomuks/tasks/setup_install.yml

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Ensure gomuks paths exist
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: directory
+    mode: '0750'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - {path: "{{ matrix_client_gomuks_data_path }}", when: true}
+    - {path: "{{ matrix_client_gomuks_data_path }}/config", when: true}
+    - {path: "{{ matrix_client_gomuks_data_path }}/logs", when: true}
+    - {path: "{{ matrix_client_gomuks_data_path }}/data", when: true}
+  when: "item.when | bool"
+
+- name: Ensure gomuks container image is pulled
+  community.docker.docker_image_pull:
+    name: "{{ matrix_client_gomuks_container_image }}"
+    pull: always
+  register: matrix_client_gomuks_container_image_pull_result
+  retries: "{{ devture_playbook_help_container_retries_count }}"
+  delay: "{{ devture_playbook_help_container_retries_delay }}"
+  until: matrix_client_gomuks_container_image_pull_result is not failed
+
+- name: Ensure gomuks configuration installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/config.yaml.j2"
+    dest: "{{ matrix_client_gomuks_data_path }}/config/config.yaml"
+    mode: '0640'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  register: matrix_client_gomuks_config_result
+
+- name: Ensure gomuks support files installed
+  ansible.builtin.template:
+    src: "{{ item.src }}"
+    dest: "{{ matrix_client_gomuks_data_path }}/{{ item.name }}"
+    mode: '0644'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - {src: "{{ role_path }}/templates/labels.j2", name: "labels"}
+    - {src: "{{ role_path }}/templates/env.j2", name: "env"}
+  register: matrix_client_gomuks_support_files_result
+
+- name: Ensure gomuks container network is created
+  when: matrix_client_gomuks_container_network != 'host'
+  community.general.docker_network:
+    enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
+    name: "{{ matrix_client_gomuks_container_network }}"
+    driver: bridge
+    driver_options: "{{ devture_systemd_docker_base_container_networks_driver_options }}"
+
+- name: Ensure matrix-client-gomuks.service installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-client-gomuks.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-client-gomuks.service"
+    mode: '0644'
+  register: matrix_client_gomuks_systemd_service_result
+
+- name: Determine whether gomuks needs a restart
+  ansible.builtin.set_fact:
+    matrix_client_gomuks_restart_necessary: >-
+      {{
+        matrix_client_gomuks_config_result.changed | default(false)
+        or matrix_client_gomuks_support_files_result.changed | default(false)
+        or matrix_client_gomuks_systemd_service_result.changed | default(false)
+        or matrix_client_gomuks_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-client-gomuks/tasks/setup_uninstall.yml

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check existence of matrix-client-gomuks.service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-client-gomuks.service"
+  register: matrix_client_gomuks_service_stat
+
+- when: matrix_client_gomuks_service_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-client-gomuks is stopped
+      ansible.builtin.service:
+        name: matrix-client-gomuks
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure matrix-client-gomuks.service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-client-gomuks.service"
+        state: absent
+
+    - name: Ensure gomuks path doesn't exist
+      ansible.builtin.file:
+        path: "{{ matrix_client_gomuks_data_path }}"
+        state: absent

roles/custom/matrix-client-gomuks/tasks/validate_config.yml

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Fail if required gomuks settings not defined
+  ansible.builtin.fail:
+    msg: >
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0"
+  with_items:
+    - {'name': 'matrix_client_gomuks_hostname', when: true}
+    - {'name': 'matrix_client_gomuks_path_prefix', when: true}
+    - {'name': 'matrix_client_gomuks_container_network', when: true}
+    - {'name': 'matrix_client_gomuks_auth_username', when: "{{ not matrix_client_gomuks_disable_auth | bool }}"}
+    - {'name': 'matrix_client_gomuks_auth_password', when: "{{ not matrix_client_gomuks_disable_auth | bool }}"}
+    - {'name': 'matrix_client_gomuks_token_key', when: true}
+
+- when: matrix_client_gomuks_container_labels_traefik_enabled | bool
+  block:
+    - name: Fail if required gomuks Traefik settings not defined
+      ansible.builtin.fail:
+        msg: >-
+          You need to define a required configuration setting (`{{ item }}`).
+      when: "lookup('vars', item, default='') | string | length == 0"
+      with_items:
+        - matrix_client_gomuks_container_labels_traefik_hostname
+        - matrix_client_gomuks_container_labels_traefik_path_prefix
+
+    - name: Fail if matrix_client_gomuks_container_labels_traefik_path_prefix ends with a slash
+      ansible.builtin.fail:
+        msg: >-
+          matrix_client_gomuks_container_labels_traefik_path_prefix (`{{ matrix_client_gomuks_container_labels_traefik_path_prefix }}`) must either be `/` or not end with a slash (e.g. `/gomuks`).
+      when: "matrix_client_gomuks_container_labels_traefik_path_prefix != '/' and matrix_client_gomuks_container_labels_traefik_path_prefix[-1] == '/'"

roles/custom/matrix-client-gomuks/templates/config.yaml.j2

@@ -0,0 +1,36 @@
+{#
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+web:
+  listen_address: {{ matrix_client_gomuks_web_listen_address | to_json }}
+{% if not matrix_client_gomuks_disable_auth | bool %}
+  username: {{ matrix_client_gomuks_auth_username | to_json }}
+  password_hash: {{ matrix_client_gomuks_auth_password_hash | to_json }}
+{% endif %}
+  token_key: {{ matrix_client_gomuks_token_key | to_json }}
+  debug_endpoints: {{ matrix_client_gomuks_debug_endpoints | to_json }}
+  event_buffer_size: {{ matrix_client_gomuks_event_buffer_size | to_json }}
+  origin_patterns:
+{% for pattern in matrix_client_gomuks_origin_patterns %}
+    - {{ pattern | to_json }}
+{% endfor %}
+  insecure_cookies: {{ matrix_client_gomuks_insecure_cookies | to_json }}
+{% if matrix_client_gomuks_disable_auth | bool %}
+  disable_auth_because_i_want_my_account_to_be_hacked: true
+{% endif %}
+matrix:
+  disable_http2: {{ matrix_client_gomuks_matrix_disable_http2 | to_json }}
+  set_presence: {{ matrix_client_gomuks_matrix_set_presence | to_json }}
+push:
+  fcm_gateway: {{ matrix_client_gomuks_push_fcm_gateway | to_json }}
+  vapid_private_key: {{ matrix_client_gomuks_push_vapid_private_key | to_json }}
+  vapid_public_key: {{ matrix_client_gomuks_push_vapid_public_key | to_json }}
+media:
+  thumbnail_size: {{ matrix_client_gomuks_media_thumbnail_size | to_json }}
+logging:
+  min_level: {{ matrix_client_gomuks_logging_min_level | to_json }}
+  writers:
+{{ matrix_client_gomuks_logging_writers | to_nice_yaml(indent=2) | indent(2, true) }}

roles/custom/matrix-client-gomuks/templates/env.j2

@@ -0,0 +1,15 @@
+{#
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+{#
+Environment variables for the matrix-client-gomuks container.
+Add custom variables by appending to matrix_client_gomuks_environment_variables_extension.
+Also see: https://pkg.go.dev/net/http#ProxyFromEnvironment for proxy support (https_proxy, etc.).
+#}
+
+GOMUKS_ROOT=/data
+
+{{ matrix_client_gomuks_environment_variables_extension }}

roles/custom/matrix-client-gomuks/templates/labels.j2

@@ -0,0 +1,56 @@
+{#
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+{% if matrix_client_gomuks_container_labels_traefik_enabled %}
+traefik.enable=true
+
+{% if matrix_client_gomuks_container_labels_traefik_docker_network %}
+traefik.docker.network={{ matrix_client_gomuks_container_labels_traefik_docker_network }}
+{% endif %}
+
+traefik.http.services.matrix-client-gomuks.loadbalancer.server.port={{ matrix_client_gomuks_container_port }}
+
+{% set middlewares = [] %}
+
+{% if matrix_client_gomuks_container_labels_traefik_compression_middleware_enabled %}
+{% set middlewares = middlewares + [matrix_client_gomuks_container_labels_traefik_compression_middleware_name] %}
+{% endif %}
+
+{% if matrix_client_gomuks_container_labels_traefik_path_prefix != '/' %}
+traefik.http.middlewares.matrix-client-gomuks-slashless-redirect.redirectregex.regex=({{ matrix_client_gomuks_container_labels_traefik_path_prefix | quote }})$
+traefik.http.middlewares.matrix-client-gomuks-slashless-redirect.redirectregex.replacement=${1}/
+{% set middlewares = middlewares + ['matrix-client-gomuks-slashless-redirect'] %}
+{% endif %}
+
+{% if matrix_client_gomuks_container_labels_traefik_path_prefix != '/' %}
+traefik.http.middlewares.matrix-client-gomuks-strip-prefix.stripprefix.prefixes={{ matrix_client_gomuks_container_labels_traefik_path_prefix }}
+{% set middlewares = middlewares + ['matrix-client-gomuks-strip-prefix'] %}
+{% endif %}
+
+{% if matrix_client_gomuks_container_labels_traefik_additional_response_headers.keys() | length > 0 %}
+{% for name, value in matrix_client_gomuks_container_labels_traefik_additional_response_headers.items() %}
+traefik.http.middlewares.matrix-client-gomuks-add-headers.headers.customresponseheaders.{{ name }}={{ value }}
+{% endfor %}
+{% set middlewares = middlewares + ['matrix-client-gomuks-add-headers'] %}
+{% endif %}
+
+traefik.http.routers.matrix-client-gomuks.rule={{ matrix_client_gomuks_container_labels_traefik_rule }}
+{% if matrix_client_gomuks_container_labels_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-client-gomuks.priority={{ matrix_client_gomuks_container_labels_traefik_priority }}
+{% endif %}
+traefik.http.routers.matrix-client-gomuks.service=matrix-client-gomuks
+{% if middlewares | length > 0 %}
+traefik.http.routers.matrix-client-gomuks.middlewares={{ middlewares | join(',') }}
+{% endif %}
+traefik.http.routers.matrix-client-gomuks.entrypoints={{ matrix_client_gomuks_container_labels_traefik_entrypoints }}
+traefik.http.routers.matrix-client-gomuks.tls={{ matrix_client_gomuks_container_labels_traefik_tls | to_json }}
+{% if matrix_client_gomuks_container_labels_traefik_tls %}
+traefik.http.routers.matrix-client-gomuks.tls.certResolver={{ matrix_client_gomuks_container_labels_traefik_tls_certResolver }}
+{% endif %}
+
+{% endif %}
+
+{{ matrix_client_gomuks_container_labels_additional_labels }}

roles/custom/matrix-client-gomuks/templates/systemd/matrix-client-gomuks.service.j2

@@ -0,0 +1,58 @@
+#jinja2: lstrip_blocks: True
+{#
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+[Unit]
+Description=Matrix gomuks web client (bouncer)
+{% for service in matrix_client_gomuks_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-client-gomuks 2>/dev/null || true'
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-client-gomuks 2>/dev/null || true'
+
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
+			--rm \
+			--name=matrix-client-gomuks \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--network={{ matrix_client_gomuks_container_network }} \
+			{% if matrix_client_gomuks_container_http_host_bind_port %}
+			-p {{ matrix_client_gomuks_container_http_host_bind_port }}:{{ matrix_client_gomuks_container_port }} \
+			{% endif %}
+			--label-file={{ matrix_client_gomuks_data_path }}/labels \
+			--env-file={{ matrix_client_gomuks_data_path }}/env \
+			--tmpfs=/tmp:rw,noexec,nosuid,size=100m \
+			--mount type=bind,src={{ matrix_client_gomuks_data_path }},dst=/data,rw \
+			{% for arg in matrix_client_gomuks_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_client_gomuks_container_image }}
+
+{% if matrix_client_gomuks_container_network != 'host' %}
+{% for network in matrix_client_gomuks_container_additional_networks %}
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-client-gomuks
+{% endfor %}
+{% endif %}
+
+ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-client-gomuks
+
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-client-gomuks 2>/dev/null || true'
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-client-gomuks 2>/dev/null || true'
+
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-client-gomuks
+
+[Install]
+WantedBy=multi-user.target

setup.yml

@@ -112,6 +112,7 @@
     - galaxy/grafana
     - custom/matrix-prometheus-services-connect
     - custom/matrix-client-element
+    - custom/matrix-client-gomuks
     - custom/matrix-client-commet
     - galaxy/hydrogen
     - galaxy/cinny