Merge pull request 'doc: Added ejabberd S3 section' (#588) from jpds/garage:doc-ejabberd-s3 into main

Reviewed-on: #588

doc/book/connect/apps/index.md

@@ -11,6 +11,7 @@ In this section, we cover the following web applications:
 | [Peertube](#peertube)     | ✅       | Supported with the website endpoint, proxifying private videos unsupported     |
 | [Mastodon](#mastodon)     | ✅       | Natively supported    |
 | [Matrix](#matrix)     | ✅       |  Tested with `synapse-s3-storage-provider`    |
+| [ejabberd](#ejabberd)     | ✅       |  `mod_s3_upload`    |
 | [Pixelfed](#pixelfed)     | ❓       |  Not yet tested    |
 | [Pleroma](#pleroma)     | ❓       |  Not yet tested    |
 | [Lemmy](#lemmy)     | ✅        |  Supported with pict-rs    |
@@ -474,6 +475,52 @@ And add a new line. For example, to run it every 10 minutes:
 
 *External link:* [matrix-media-repo Documentation > S3](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html)
 
+## ejabberd
+
+ejabberd is an XMPP server implementation which, with the `mod_s3_upload`
+module in the [ejabberd-contrib](https://github.com/processone/ejabberd-contrib)
+repository, can be integrated to store chat media files in Garage.
+
+For uploads, this module leverages presigned URLs - this allows XMPP clients to
+directly send media to Garage. Receiving clients then retrieve this media
+through the [static website](@/documentation/cookbook/exposing-websites.md)
+functionality.
+
+As the data itself is publicly accessible to someone with knowledge of the
+object URL - users are recommended to use
+[E2EE](@/documentation/cookbook/encryption.md) to protect this data-at-rest
+from unauthorized access.
+
+Install the module with:
+
+```bash
+ejabberdctl module_install mod_s3_upload
+```
+
+Create the required key and bucket with:
+
+```bash
+garage key new --name ejabberd
+garage bucket create objects.xmpp-server.fr
+garage bucket allow objects.xmpp-server.fr --read --write --key ejabberd
+garage bucket website --allow objects.xmpp-server.fr
+```
+
+The module can then be configured with:
+
+```
+  mod_s3_upload:
+    #bucket_url: https://objects.xmpp-server.fr.my-garage-instance.mydomain.tld
+    bucket_url: https://my-garage-instance.mydomain.tld/objects.xmpp-server.fr
+    access_key_id: GK...
+    access_key_secret: ...
+    region: garage
+    download_url: https://objects.xmpp-server.fr
+```
+
+Other configuration options can be found in the
+[configuration YAML file](https://github.com/processone/ejabberd-contrib/blob/master/mod_s3_upload/conf/mod_s3_upload.yml).
+
 ## Pixelfed
 
 [Pixelfed Technical Documentation > Configuration](https://docs.pixelfed.org/technical-documentation/env.html#filesystem)
@@ -539,7 +586,7 @@ secret_key = 'abcdef0123456789...'
 
 ```
 PICTRS__STORE__TYPE=object_storage
-PICTRS__STORE__ENDPOINT=http:/my-garage-instance.mydomain.tld:3900
+PICTRS__STORE__ENDPOINT=http://my-garage-instance.mydomain.tld:3900
 PICTRS__STORE__BUCKET_NAME=pictrs-data
 PICTRS__STORE__REGION=garage
 PICTRS__STORE__ACCESS_KEY=GK...

doc/book/cookbook/encryption.md

@@ -104,5 +104,13 @@ Implementations are very specific to the various applications. Examples:
   in Matrix are probably encrypted using symmetric encryption, with a key that is
   distributed in the end-to-end encrypted message that contains the link to the object.
 
+- XMPP: clients normally support either OMEMO / OpenPGP for the E2EE of user
+  messages. Media files are encrypted per
+  [XEP-0454](https://xmpp.org/extensions/xep-0454.html).
+
 - Aerogramme: use the user's password as a key to decrypt data in the user's bucket
 
+- Cyberduck: comes with support for
+  [Cryptomator](https://docs.cyberduck.io/cryptomator/) which allows users to
+  create client-side vaults to encrypt files in before they are uploaded to a
+  cloud storage endpoint.

doc/book/operations/durability-repairs.md

@@ -26,8 +26,11 @@ their content is correct, by verifying their hash. Any block found to be corrupt
 (e.g. by bitrot or by an accidental manipulation of the datastore) will be
 restored from another node that holds a valid copy.
 
-A scrub is run automatically by Garage every 30 days. It can also be launched
+Scrubs are automatically scheduled by Garage to run every 25-35 days (the
-manually using `garage repair scrub start`.
+actual time is randomized to spread load across nodes). The next scheduled run
+can be viewed with `garage worker get`.
+
+A scrub can also be launched manually using `garage repair scrub start`.
 
 To view the status of an ongoing scrub, first find the task ID of the scrub worker
 using `garage worker list`. Then, run `garage worker info <scrub_task_id>` to
@@ -79,7 +82,7 @@ To help make the difference between cases 1 and cases 2 and 3, you may use the
 `garage block info` command to see which objects hold a reference to each block.
 
 In the second case (transient errors), Garage will try to fetch the block again
-after a certain time, so the error should disappear natuarlly. You can also
+after a certain time, so the error should disappear naturally. You can also
 request Garage to try to fetch the block immediately using `garage block retry-now`
 if you have fixed the transient issue.