diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c8e400ad..c8c65807c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,30 @@ +# 2026-02-09 + +## (BC Break) matrix-media-repo datastore IDs are now required in `vars.yml` + +**Affects**: users with [matrix-media-repo](docs/configuring-playbook-matrix-media-repo.md) enabled (`matrix_media_repo_enabled: true`) + +The `matrix_media_repo_datastore_file_id` and `matrix_media_repo_datastore_s3_id` variables are no longer auto-configured with values. They must now be explicitly defined in your `vars.yml` file. The playbook will fail with a helpful error if they are not set (when needed). + +These were never meant to be auto-configured. They were derived from `matrix_homeserver_generic_secret_key`, which is intended for secrets that are OK to change subsequently (and Ansible would assist in propagating these changes). matrix-media-repo datastore IDs are not secrets — they are static identifiers linking media to storage backends, and **must not change** after first use. + +**For existing installations**, retrieve your current values from the server: + +```sh +grep 'id:' /matrix/media-repo/config/media-repo.yaml +``` + +Then add to your `vars.yml`: + +```yaml +matrix_media_repo_datastore_file_id: "YOUR_FILE_DATASTORE_ID_HERE" + +# Only if you use S3 storage: +# matrix_media_repo_datastore_s3_id: "YOUR_S3_DATASTORE_ID_HERE" +``` + +**Why do this?**: This change allows us to **remove the [passlib](https://passlib.readthedocs.io/en/stable/index.html) Python library** from the [prerequisites](docs/prerequisites.md), as it was the last component that depended on it. + # 2026-02-08 ## Zulip bridge has been removed from the playbook diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index acadf8cf2..71e09ab22 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/docs/configuring-playbook-matrix-media-repo.md @@ -24,8 +24,21 @@ To enable matrix-media-repo, add the following configuration to your `inventory/ ```yaml matrix_media_repo_enabled: true + +# Any unique alphanumeric string. Cannot be changed after first use. +# For new installations, generate one with: pwgen -s 64 1 +# For existing installations, see below. +matrix_media_repo_datastore_file_id: "CHANGE_ME_TO_A_UNIQUE_VALUE" ``` +**For existing installations**: retrieve the current datastore ID from the server's config file before proceeding: + +```sh +grep 'id:' /matrix/media-repo/config/media-repo.yaml +``` + +Then use that value for `matrix_media_repo_datastore_file_id`. This is not a secret — it is a plain identifier used by matrix-media-repo to link media files to their storage backend. + By default, the media-repo will use the local filesystem for data storage. You can alternatively use a `s3` cloud backend as well. Access token caching is also enabled by default since the logout endpoints are proxied through the media repo. ### Enable metrics @@ -109,6 +122,11 @@ matrix_media_repo_admins: [] matrix_media_repo_datastore_file_for_kinds: ["thumbnails", "remote_media", "local_media", "archives"] matrix_media_repo_datastore_s3_for_kinds: [] +# Required when S3 storage is enabled (matrix_media_repo_datastore_s3_for_kinds is non-empty). +# Any unique alphanumeric string. Cannot be changed after first use. +# For new installations, generate one with: pwgen -s 64 1 +# matrix_media_repo_datastore_s3_id: "" + # The s3 uploader needs a temporary location to buffer files to reduce memory usage on # small file uploads. If the file size is unknown, the file is written to this location # before being uploaded to s3 (then the file is deleted). If you aren't concerned about diff --git a/docs/prerequisites.md b/docs/prerequisites.md index bd0ad4316..5ed76ad2c 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -23,8 +23,6 @@ We will be using `example.com` as the domain in the following instruction. Pleas - [Ansible](http://ansible.com/) program. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible. -- [passlib](https://passlib.readthedocs.io/en/stable/index.html) Python library. See [this official documentation](https://passlib.readthedocs.io/en/stable/install.html#installation-instructions) for an instruction to install it. On most distros, you need to install some `python-passlib` or `py3-passlib` package, etc. - - [`git`](https://git-scm.com/) as the recommended way to download the playbook. `git` may also be required on the server if you will be [self-building](self-building.md) components. - [`just`](https://github.com/casey/just) for running `just roles`, `just update`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually. Take a look at this documentation for more information: [Running `just` commands](just.md). diff --git a/roles/custom/matrix-media-repo/defaults/main.yml b/roles/custom/matrix-media-repo/defaults/main.yml index 68a5dafe8..37d19d64d 100755 --- a/roles/custom/matrix-media-repo/defaults/main.yml +++ b/roles/custom/matrix-media-repo/defaults/main.yml @@ -414,8 +414,9 @@ matrix_media_repo_shared_secret_auth_token: "PutSomeRandomSecureValueHere" # thumbnails and other misc data is also stored in these places. The media repo, when looking # for a datastore to use, will always use the smallest datastore first. -# ID for the file datastore (cannot change). Alphanumeric recommended. -matrix_media_repo_datastore_file_id: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'filestore.db', rounds=655555) | to_uuid }}" +# ID for the file datastore. Any unique alphanumeric string (e.g. generated via `pwgen -s 64 1`). +# This value CANNOT be changed after media has been stored — matrix-media-repo ties media to this ID. +matrix_media_repo_datastore_file_id: "" # Datastores can be split into many areas when handling uploads. Media is still de-duplicated # across all datastores (local content which duplicates remote content will re-use the remote @@ -434,8 +435,9 @@ matrix_media_repo_datastore_file_for_kinds: ["thumbnails", "remote_media", "loca # Path to datastore, relative to matrix-media-repo directory root matrix_media_repo_datastore_opts_path: "/data/media" -# ID for the s3 datastore (cannot change). Alphanumeric recommended. -matrix_media_repo_datastore_s3_id: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 's3store.db', rounds=655555) | to_uuid }}" +# ID for the S3 datastore. Any unique alphanumeric string (e.g. generated via `pwgen -s 64 1`). +# This value CANNOT be changed after media has been stored — matrix-media-repo ties media to this ID. +matrix_media_repo_datastore_s3_id: "" # Datastores can be split into many areas when handling uploads. Media is still de-duplicated # across all datastores (local content which duplicates remote content will re-use the remote diff --git a/roles/custom/matrix-media-repo/tasks/validate_config.yml b/roles/custom/matrix-media-repo/tasks/validate_config.yml index a531b0a4b..03f67e326 100644 --- a/roles/custom/matrix-media-repo/tasks/validate_config.yml +++ b/roles/custom/matrix-media-repo/tasks/validate_config.yml @@ -15,6 +15,8 @@ - {'name': 'matrix_media_repo_database_hostname', when: true} - {'name': 'matrix_media_repo_container_labels_traefik_internal_media_entrypoints', when: "{{ matrix_media_repo_container_labels_traefik_internal_media_enabled }}"} - {'name': 'matrix_media_repo_container_labels_traefik_internal_matrix_client_media_entrypoints', when: "{{ matrix_media_repo_container_labels_traefik_internal_matrix_client_media_enabled }}"} + - {'name': 'matrix_media_repo_datastore_file_id', when: "{{ (matrix_media_repo_datastore_file_for_kinds | length) > 0 }}"} + - {'name': 'matrix_media_repo_datastore_s3_id', when: "{{ (matrix_media_repo_datastore_s3_for_kinds | length) > 0 }}"} - name: (Deprecation) Catch and report renamed matrix-media-repo settings ansible.builtin.fail: