Remove the custom Element Web welcome page

Element Web redesigned its welcome page into a built-in component
(element-hq/element-web#33211, first released in spring 2026) and no
longer falls back to loading welcome.html. The custom page the playbook
installed had therefore silently stopped having any effect, and it was a
fork of an upstream file that upstream has deleted (its button icon
assets are already missing from current Element Web builds).

Remove the welcome.html shipping and the variables that only applied to
it (matrix_client_element_welcome_headline, _welcome_text,
_welcome_logo_link, _page_template_welcome_path), rejecting them in
validate_config.yml with pointers to the alternatives. Logo and
background customization keep working through Element Web's branding
options, which the new welcome page still honors. A fully custom page
can be self-hosted and wired via embedded_pages.welcome_url.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -1,5 +1,27 @@
 # 2026-07-14
 
+## The playbook no longer ships a custom welcome page for Element Web
+
+Element Web [redesigned its welcome page](https://github.com/element-hq/element-web/pull/33211) (the screen shown at `/#/welcome` before logging in) into a built-in component and no longer loads a custom `welcome.html` file by default. Since the playbook upgraded to an Element Web version containing that change (spring 2026), the custom welcome page the playbook installed (and the variables customizing it) had silently stopped having any effect.
+
+The playbook now embraces the new upstream behavior and no longer ships its own `welcome.html`. The following variables have been removed and the playbook will let you know if you're still using them: `matrix_client_element_welcome_headline`, `matrix_client_element_welcome_text`, `matrix_client_element_welcome_logo_link` and `matrix_client_element_page_template_welcome_path`.
+
+Most welcome page customizations keep working, because they go through Element Web's branding configuration, which the new welcome page still honors:
+
+- a custom logo, via `matrix_client_element_welcome_logo` (or `matrix_client_element_branding_auth_header_logo_url`)
+- a custom background, via `matrix_client_element_branding_welcome_background_url`
+
+If you need a fully custom welcome page, you can self-host an HTML page and point Element Web at it, like this:
+
+```yaml
+matrix_client_element_configuration_extension_json: |
+  {
+    "embedded_pages": {
+      "welcome_url": "https://example.com/my-welcome.html"
+    }
+  }
+```
+
 ## BorgBackup now includes Synapse's local thumbnails
 
 For Synapse servers, the built-in [BorgBackup](./docs/configuring-playbook-backup-borg.md) integration no longer excludes the media store's `local_thumbnails` directory from backups.

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

@@ -189,15 +189,10 @@ matrix_client_element_room_directory_servers: ['matrix.org']
 # Branding of Element
 matrix_client_element_brand: "Element"
 
-# URL to Logo on welcome page
+# URL to the logo shown on the welcome and login pages.
+# This is the default for `matrix_client_element_branding_auth_header_logo_url` below.
 matrix_client_element_welcome_logo: "themes/element/img/logos/element-logo.svg"
 
-# URL of link on welcome image
-matrix_client_element_welcome_logo_link: "https://element.io"
-
-matrix_client_element_welcome_headline: "_t(\"welcome_to_element\")"
-matrix_client_element_welcome_text: "_t(\"powered_by_matrix_with_logo\")"
-
 # Links, shown in footer of welcome page:
 # [{"text": "Link text", "url": "https://link.target"}, {"text": "Other link"}]
 matrix_client_element_branding_auth_footer_links: ~  # noqa var-naming
@@ -269,8 +264,6 @@ matrix_client_element_element_call_brand: "Element Call"
 # Controls the `element_call.use_exclusively` setting in the Element Web configuration.
 matrix_client_element_element_call_use_exclusively: true
 
-matrix_client_element_page_template_welcome_path: "{{ role_path }}/templates/welcome.html.j2"
-
 # By default, there's no Element Web homepage (when logged in). If you wish to have one,
 # point this to a `home.html` template file on your local filesystem.
 matrix_client_element_embedded_pages_home_path: ~

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

@@ -97,7 +97,6 @@
   with_items:
     - {src: "{{ role_path }}/templates/labels.j2", name: "labels"}
     - {src: "{{ role_path }}/templates/env.j2", name: "env"}
-    - {src: "{{ matrix_client_element_page_template_welcome_path }}", name: "welcome.html"}
     - {src: "{{ matrix_client_element_embedded_pages_home_path }}", name: "home.html"}
   when: "item.src is not none"
   register: matrix_client_element_support_files_result
@@ -113,6 +112,8 @@
     state: absent
   with_items:
     - {src: "{{ matrix_client_element_embedded_pages_home_path }}", name: "home.html"}
+    # The playbook no longer ships a custom welcome.html (Element Web renders its own built-in welcome page).
+    - {src: ~, name: "welcome.html"}
   when: "item.src is none"
 
 - name: Ensure Element Web container network is created

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

@@ -30,6 +30,10 @@
     - {'old': 'matrix_client_element_docker_image_registry_prefix_upstream_default', 'new': 'matrix_client_element_container_image_registry_prefix_upstream_default'}
     - {'old': 'matrix_client_element_docker_src_files_path', 'new': 'matrix_client_element_container_src_files_path'}
     - {'old': 'matrix_client_element_container_image_force_pull', 'new': '<removed> (the new community.docker.docker_image_pull module handles this natively)'}
+    - {'old': 'matrix_client_element_welcome_headline', 'new': '<removed> (Element Web now renders its own built-in welcome page and no longer loads the custom welcome.html this variable applied to; a logo and background can still be customized via matrix_client_element_branding_auth_header_logo_url and matrix_client_element_branding_welcome_background_url, and a fully custom page can be self-hosted and wired via embedded_pages.welcome_url in matrix_client_element_configuration_extension_json)'}
+    - {'old': 'matrix_client_element_welcome_text', 'new': '<removed> (Element Web now renders its own built-in welcome page and no longer loads the custom welcome.html this variable applied to; see matrix_client_element_welcome_headline for alternatives)'}
+    - {'old': 'matrix_client_element_welcome_logo_link', 'new': '<removed> (Element Web now renders its own built-in welcome page and no longer loads the custom welcome.html this variable applied to; see matrix_client_element_welcome_headline for alternatives)'}
+    - {'old': 'matrix_client_element_page_template_welcome_path', 'new': '<removed> (Element Web now renders its own built-in welcome page; a fully custom page can be self-hosted and wired via embedded_pages.welcome_url in matrix_client_element_configuration_extension_json)'}
 
 - name: Fail if required Element Web settings not defined
   ansible.builtin.fail:

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

@@ -43,7 +43,6 @@ ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
 			{% if matrix_client_element_embedded_pages_home_path is not none %}
 			--mount type=bind,src={{ matrix_client_element_data_path }}/home.html,dst=/app/home.html,ro \
 			{% endif %}
-			--mount type=bind,src={{ matrix_client_element_data_path }}/welcome.html,dst=/app/welcome.html,ro \
 			{% if matrix_client_element_container_healthcheck_cmd %}
 			--health-cmd="{{ matrix_client_element_container_healthcheck_cmd }}" \
 			{% endif %}

roles/custom/matrix-client-element/templates/welcome.html.j2

@@ -1,214 +0,0 @@
-#jinja2: lstrip_blocks: True
-<style type="text/css">
-
-/* we deliberately inline style here to avoid flash-of-CSS problems, and to avoid
- * voodoo where we have to set display: none by default
- */
-
-h1::after {
-    content: "!";
-}
-
-.mx_Parent {
-    display: -webkit-box;
-    display: -webkit-flex;
-    display: -ms-flexbox;
-    display: flex;
-    -webkit-box-orient: vertical;
-    -webkit-box-direction: normal;
-    -webkit-flex-direction: column;
-    -ms-flex-direction: column;
-    flex-direction: column;
-    -webkit-box-pack: center;
-    -webkit-justify-content: center;
-    -ms-flex-pack: center;
-    justify-content: center;
-    -webkit-box-align: center;
-    -webkit-align-items: center;
-    -ms-flex-align: center;
-    align-items: center;
-    text-align: center;
-    padding: 25px 35px;
-    color: #2e2f32;
-}
-
-.mx_Logo {
-    height: 54px;
-    margin-top: 2px;
-}
-
-.mx_ButtonGroup {
-    margin-top: 10px;
-}
-
-.mx_ButtonRow {
-    display: -webkit-box;
-    display: -webkit-flex;
-    display: -ms-flexbox;
-    display: flex;
-    -webkit-justify-content: space-around;
-    -ms-flex-pack: distribute;
-    justify-content: space-around;
-    -webkit-box-align: center;
-    -webkit-align-items: center;
-    -ms-flex-align: center;
-    align-items: center;
-    justify-content: space-between;
-    box-sizing: border-box;
-    margin: 12px 0 0;
-}
-
-.mx_ButtonRow > * {
-    margin: 0 10px;
-}
-
-.mx_ButtonRow > *:first-child {
-    margin-left: 0;
-}
-
-.mx_ButtonRow > *:last-child {
-    margin-right: 0;
-}
-
-.mx_ButtonParent {
-    display: -webkit-box;
-    display: -webkit-flex;
-    display: -ms-flexbox;
-    display: flex;
-    padding: 10px 20px;
-    -webkit-box-orient: horizontal;
-    -webkit-box-direction: normal;
-    -webkit-flex-direction: row;
-    -ms-flex-direction: row;
-    flex-direction: row;
-    -webkit-box-pack: center;
-    -webkit-justify-content: center;
-    -ms-flex-pack: center;
-    justify-content: center;
-    -webkit-box-align: center;
-    -webkit-align-items: center;
-    -ms-flex-align: center;
-    align-items: center;
-    border-radius: 4px;
-    width: 150px;
-    background-repeat: no-repeat;
-    background-position: 10px center;
-    text-decoration: none;
-    color: #2e2f32 !important;
-}
-
-.mx_ButtonLabel {
-    margin-left: 20px;
-}
-
-.mx_Header_title {
-    font-size: 24px;
-    font-weight: 600;
-    margin: 20px 0 0;
-}
-
-.mx_Header_subtitle {
-    font-size: 12px;
-    font-weight: normal;
-    margin: 8px 0 0;
-}
-
-.mx_ButtonSignIn {
-    background-color: #368BD6;
-    color: white !important;
-}
-
-.mx_ButtonCreateAccount {
-    background-color: #0DBD8B;
-    color: white !important;
-}
-
-.mx_SecondaryButton {
-    background-color: #FFFFFF;
-    color: #2E2F32;
-}
-
-.mx_Button_iconSignIn {
-    background-image: url('welcome/images/icon-sign-in.svg');
-}
-.mx_Button_iconCreateAccount {
-    background-image: url('welcome/images/icon-create-account.svg');
-}
-.mx_Button_iconHelp {
-    background-image: url('welcome/images/icon-help.svg');
-}
-.mx_Button_iconRoomDirectory {
-    background-image: url('welcome/images/icon-room-directory.svg');
-}
-
-/*
-.mx_WelcomePage_loggedIn is applied by EmbeddedPage from the Welcome component
-If it is set on the page, we should show the buttons. Otherwise, we have to assume
-we don't have an account and should hide them. No account == no guest account either.
- */
-.mx_WelcomePage:not(.mx_WelcomePage_loggedIn) .mx_WelcomePage_guestFunctions {
-    display: none;
-}
-
-.mx_ButtonRow.mx_WelcomePage_guestFunctions {
-    margin-top: 20px;
-}
-.mx_ButtonRow.mx_WelcomePage_guestFunctions > div {
-    margin: 0 auto;
-}
-
-@media only screen and (max-width: 480px) {
-    .mx_ButtonRow {
-        flex-direction: column;
-    }
-
-    .mx_ButtonRow > * {
-        margin: 0 0 10px 0;
-    }
-}
-
-/* Element Web (with its default use_system_theme behavior) renders its dark background
-   when the system prefers a dark color scheme, so the welcome text follows the same signal.
-   #ebeef2 is the light text color Element uses with the dark theme. */
-@media (prefers-color-scheme: dark) {
-    .mx_Parent {
-        color: #ebeef2;
-    }
-}
-
-</style>
-
-<div class="mx_Parent">
-    <a href="{{ matrix_client_element_welcome_logo_link }}" target="_blank" rel="noopener">
-        <img src="{{ matrix_client_element_welcome_logo }}" alt="" class="mx_Logo"/>
-    </a>
-    <h1 class="mx_Header_title">{{ matrix_client_element_welcome_headline }}</h1>
-    <h4 class="mx_Header_subtitle">{{ matrix_client_element_welcome_text }}</h4>
-    <div class="mx_ButtonGroup">
-        <div class="mx_ButtonRow">
-            <a href="#/login" class="mx_ButtonParent mx_ButtonSignIn mx_Button_iconSignIn">
-                <div class="mx_ButtonLabel">_t("action|sign_in")</div>
-            </a>
-{% if matrix_client_element_registration_enabled %}
-            <a href="#/register" class="mx_ButtonParent mx_ButtonCreateAccount mx_Button_iconCreateAccount">
-                <div class="mx_ButtonLabel">_t("action|create_account")</div>
-            </a>
-{% endif %}
-        </div>
-{% if matrix_client_element_disable_guests != true %}
-        <!-- The comments below are meant to be used by Ansible as a quick way
-             to strip out the marked content when desired.
-             See https://github.com/element-hq/riot-web/issues/8622.
-             TODO: Convert to config option if possible. -->
-        <!-- BEGIN Ansible: Remove these lines when guest access is disabled -->
-        <div class="mx_ButtonRow mx_WelcomePage_guestFunctions">
-            <div>
-                <a href="#/directory" class="mx_ButtonParent mx_SecondaryButton mx_Button_iconRoomDirectory">
-                    <div class="mx_ButtonLabel">_t("action|explore_rooms")</div>
-                </a>
-            </div>
-        </div>
-        <!-- END Ansible: Remove these lines when guest access is disabled -->
-{% endif %}
-    </div>
-</div>

roles/custom/matrix-client-element/templates/welcome.html.j2.license

@@ -1,9 +0,0 @@
-SPDX-FileCopyrightText: 2019 Daniel Hoffend
-SPDX-FileCopyrightText: 2019 Hugues De Keyzer
-SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
-SPDX-FileCopyrightText: 2020 Clement Renaud
-SPDX-FileCopyrightText: 2020 Stefan Warnat
-SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
-SPDX-FileCopyrightText: 2024 MDAD project contributors
-
-SPDX-License-Identifier: AGPL-3.0-or-later