From 424e5c66464ee1de70615000d244cfd82243a2f2 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 4 Mar 2025 20:49:21 +0900 Subject: [PATCH 1/5] Update docs/configuring-playbook-synapse-simple-antispam.md: add the section for installing Signed-off-by: Suguru Hirahara --- ...onfiguring-playbook-synapse-simple-antispam.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/configuring-playbook-synapse-simple-antispam.md b/docs/configuring-playbook-synapse-simple-antispam.md index 35b106a60..b5d99844c 100644 --- a/docs/configuring-playbook-synapse-simple-antispam.md +++ b/docs/configuring-playbook-synapse-simple-antispam.md @@ -1,6 +1,6 @@ @@ -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: + + +```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. From 70b4fd0489d8c8e886d04206ae5b696f1de390f5 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 4 Mar 2025 20:57:57 +0900 Subject: [PATCH 2/5] Update docs/configuring-playbook-synapse-s3-storage-provider.md: adopt the common introduction and add the section for installing Signed-off-by: Suguru Hirahara --- ...ng-playbook-synapse-s3-storage-provider.md | 23 ++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/configuring-playbook-synapse-s3-storage-provider.md b/docs/configuring-playbook-synapse-s3-storage-provider.md index eccd58c02..0d7c312ce 100644 --- a/docs/configuring-playbook-synapse-s3-storage-provider.md +++ b/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: + + +```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/…`): From f059b72bb58572953c906d295efddb924c7f26c9 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 4 Mar 2025 21:20:57 +0900 Subject: [PATCH 3/5] Update docs/configuring-playbook-s3-goofys.md - Adopt the common instruction - Add a copyright header Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-s3-goofys.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/configuring-playbook-s3-goofys.md b/docs/configuring-playbook-s3-goofys.md index 2efdac86e..2e3e76bea 100644 --- a/docs/configuring-playbook-s3-goofys.md +++ b/docs/configuring-playbook-s3-goofys.md @@ -1,12 +1,21 @@ + + # Storing Matrix media files on Amazon S3 with Goofys (optional) -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. +The playbook can install and configure [Goofys](https://github.com/kahing/goofys) for you. -Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md). +Goofys makes it possible to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service) object storage. -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. +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. -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. +**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 From 0b9e4df5d336959549e1c28b5b76f61d58f703eb Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 4 Mar 2025 21:29:29 +0900 Subject: [PATCH 4/5] Update docs: add "Synapse" to the title of configuring-playbook-s3-goofys.md Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-s3-goofys.md | 2 +- docs/configuring-playbook.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-s3-goofys.md b/docs/configuring-playbook-s3-goofys.md index 2e3e76bea..8fcf145a0 100644 --- a/docs/configuring-playbook-s3-goofys.md +++ b/docs/configuring-playbook-s3-goofys.md @@ -5,7 +5,7 @@ SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara SPDX-License-Identifier: AGPL-3.0-or-later --> -# Storing Matrix media files on Amazon S3 with Goofys (optional) +# Storing Synapse media files on Amazon S3 with Goofys (optional) The playbook can install and configure [Goofys](https://github.com/kahing/goofys) for you. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 769ec21ab..1e8762ca4 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -120,7 +120,7 @@ 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 Synapse media files on Amazon S3 with Goofys](configuring-playbook-s3-goofys.md) - [Storing Synapse media files on Amazon S3 or another compatible Object Storage](configuring-playbook-s3.md) From ed23f9b5dbf710d257af0c37bc8c68a564c3ba39 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 4 Mar 2025 21:32:11 +0900 Subject: [PATCH 5/5] Update docs/configuring-playbook.md: file storage section - Add a link to configuring-playbook-synapse-s3-storage-provider.md - Sort items Signed-off-by: Suguru Hirahara --- docs/configuring-playbook.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 1e8762ca4..6a867b8d6 100644 --- a/docs/configuring-playbook.md +++ b/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 Synapse 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