diff --git a/roles/custom/matrix-rageshake/defaults/main.yml b/roles/custom/matrix-rageshake/defaults/main.yml
index 4f574d3f6..a1bbe242b 100644
--- a/roles/custom/matrix-rageshake/defaults/main.yml
+++ b/roles/custom/matrix-rageshake/defaults/main.yml
@@ -31,12 +31,29 @@ matrix_rageshake_systemd_wanted_services_list: []
 
 matrix_rageshake_config_api_prefix: "https://{{ matrix_server_fqn_rageshake }}/api/"
 
-# Rageshake Settings
-
-# Additional config  to pass to the rageshake.
-# See https://github.com/matrix-org/rageshake/blob/master/rageshake.sample.yaml
+# Default Rageshake configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
 #
-# Example:
-# matrix_rageshake_config: |
-#   github_token: secrettoken
-matrix_rageshake_config: ""
+# For a more advanced customization, you can extend the default (see `matrix_rageshake_configuration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_rageshake_configuration_yaml: "{{ lookup('template', 'templates/config.yml.j2') }}"
+
+matrix_rageshake_configuration_extension_yaml: |
+  # Your custom YAML configuration for Synapse goes here.
+  # This configuration extends the default starting configuration (`matrix_rageshake_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_rageshake_configuration_yaml`.
+  #
+  # Example configuration extension follows:
+  #
+  # github_project_mappings:
+  #   my-app: octocat/HelloWorld
+
+matrix_rageshake_configuration_extension: "{{ matrix_rageshake_configuration_extension_yaml | from_yaml if matrix_rageshake_configuration_extension_yaml | from_yaml is mapping else {} }}"
+
+# Holds the final Synapse configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_rageshake_configuration_yaml`.
+matrix_rageshake_configuration: "{{ matrix_rageshake_configuration_yaml | from_yaml | combine(matrix_rageshake_configuration_extension, recursive=True) }}"
diff --git a/roles/custom/matrix-rageshake/tasks/install.yml b/roles/custom/matrix-rageshake/tasks/install.yml
index b081960e5..3f4d64c5d 100644
--- a/roles/custom/matrix-rageshake/tasks/install.yml
+++ b/roles/custom/matrix-rageshake/tasks/install.yml
@@ -16,8 +16,8 @@
   when: "item.when | bool"
 
 - name: Ensure rageshake config file created
-  ansible.builtin.template:
-    src: "{{ role_path }}/templates/config.j2"
+  ansible.builtin.copy:
+    content: "{{ matrix_rageshake_configuration | to_nice_yaml(indent=2, width=999999) }}"
     dest: "{{ matrix_rageshake_config_path }}/config.yml"
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
@@ -63,4 +63,3 @@
     src: "{{ role_path }}/templates/systemd/matrix-rageshake.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-rageshake.service"
     mode: 0644
-  register: matrix_rageshake_systemd_service_result
diff --git a/roles/custom/matrix-rageshake/templates/config.j2 b/roles/custom/matrix-rageshake/templates/config.j2
deleted file mode 100644
index 08c90438c..000000000
--- a/roles/custom/matrix-rageshake/templates/config.j2
+++ /dev/null
@@ -1,2 +0,0 @@
-api_prefix: {{ matrix_rageshake_config_api_prefix | to_json }}
-{{ matrix_rageshake_config | to_nice_yaml(indent=2, width=999999) }}
diff --git a/roles/custom/matrix-rageshake/templates/config.yml.j2 b/roles/custom/matrix-rageshake/templates/config.yml.j2
new file mode 100644
index 000000000..6b0c2664d
--- /dev/null
+++ b/roles/custom/matrix-rageshake/templates/config.yml.j2
@@ -0,0 +1,4 @@
+# Default configuration for Rageshake.
+# To extend it, use `matrix_rageshake_configuration_extension_yaml`.
+
+api_prefix: {{ matrix_rageshake_config_api_prefix | to_json }}