Remove passlib dependency by making matrix-media-repo datastore IDs user-provided

These IDs were incorrectly auto-derived from matrix_homeserver_generic_secret_key,
which is meant for secrets that are OK to change. Datastore IDs are static
identifiers that must never change after first use.

The playbook now requires users to explicitly set matrix_media_repo_datastore_file_id
(and matrix_media_repo_datastore_s3_id when S3 is enabled) in vars.yml, with
validation that fails early if they are missing.

This was the last usage of passlib, which is now removed from prerequisites.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

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

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).

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

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: