Merge pull request #4142 from luixxiul/fix

Update docs for S3 media storage configuration for Synapse

docs/configuring-playbook-s3-goofys.md

@@ -1,12 +1,21 @@
-# Storing Matrix media files on Amazon S3 with Goofys (optional)
+<!--
+SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service), you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md).
+# Storing Synapse media files on Amazon S3 with Goofys (optional)
 
-Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
+The playbook can install and configure [Goofys](https://github.com/kahing/goofys) for you.
 
-If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
+Goofys makes it possible to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service) object storage.
+
+See the project's [documentation](https://github.com/kahing/goofys/blob/master/README.md) to learn what it does and why it might be useful to you.
+
+**Note**: as performance of a Goofys-backed media store may not be ideal, you may wish to use [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) instead, another (and better performing) way to mount a S3 bucket for Synapse.
+
+If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), you can refer our migration instructions below.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-synapse-s3-storage-provider.md

@@ -2,16 +2,20 @@
 SPDX-FileCopyrightText: 2022 - 2023 Slavi Pantaleev
 SPDX-FileCopyrightText: 2023 Cody Wyatt Neiman
 SPDX-FileCopyrightText: 2023 MDAD project contributors
-SPDX-FileCopyrightText: 2024 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
 # Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider (optional)
 
-If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service), you can use the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) media provider module for Synapse.
+The playbook can install and configure the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) for you.
 
-An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).
+It is a media provider module for Synapse to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service) object storage.
+
+See the project's [documentation](https://github.com/matrix-org/synapse-s3-storage-provider/blob/main/README.md) to learn what it does and why it might be useful to you.
+
+**Note**: alternatively you can use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md) despite worse performance.
 
 ## How it works?
 
@@ -62,6 +66,19 @@ Take a look at:
 
 - `roles/custom/matrix-synapse/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 
+## Installing
+
+After configuring the playbook, run it 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
 
 If you have existing files in Synapse's media repository (`/matrix/synapse/storage/media-store/…`):

docs/configuring-playbook-synapse-simple-antispam.md

@@ -1,6 +1,6 @@
 <!--
 SPDX-FileCopyrightText: 2019 Slavi Pantaleev
-SPDX-FileCopyrightText: 2024 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
@@ -24,3 +24,16 @@ matrix_synapse_ext_spam_checker_synapse_simple_antispam_config_blocked_homeserve
 - example.com
 - example.net
 ```
+
+## Installing
+
+After configuring the playbook, run it 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.

docs/configuring-playbook.md

@@ -120,11 +120,13 @@ Extend and modify how users are authenticated on your homeserver.
 
 Use alternative file storage to the default `media_store` folder.
 
-- [Storing Matrix media files on Amazon S3 with Goofys](configuring-playbook-s3-goofys.md)
+- [Storing Matrix media files using matrix-media-repo](configuring-playbook-matrix-media-repo.md)
 
 - [Storing Synapse media files on Amazon S3 or another compatible Object Storage](configuring-playbook-s3.md)
 
-- [Storing Matrix media files using matrix-media-repo](configuring-playbook-matrix-media-repo.md)
+- [Storing Synapse media files on Amazon S3 with Goofys](configuring-playbook-s3-goofys.md)
+
+- [Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md)
 
 ### Bridging other networks