Merge branch 'main' into next

5 files changed, 182 insertions, 53 deletions

diff --git a/doc/book/connect/_index.md b/doc/book/connect/_index.md
index ca44ac17..93a2b87e 100644
--- a/doc/book/connect/_index.md
+++ b/doc/book/connect/_index.md
@@ -10,11 +10,12 @@ Garage implements the Amazon S3 protocol, which makes it compatible with many ex
 
 In particular, you will find here instructions to connect it with:
 
-  - [Browsing tools](@/documentation/connect/cli.md)
   - [Applications](@/documentation/connect/apps/index.md)
-  - [Website hosting](@/documentation/connect/websites.md)
-  - [Software repositories](@/documentation/connect/repositories.md)
+  - [Browsing tools](@/documentation/connect/cli.md)
   - [FUSE](@/documentation/connect/fs.md)
+  - [Observability](@/documentation/connect/observability.md)
+  - [Software repositories](@/documentation/connect/repositories.md)
+  - [Website hosting](@/documentation/connect/websites.md)
 
 ### Generic instructions
 
diff --git a/doc/book/connect/apps/index.md b/doc/book/connect/apps/index.md
index 78d9310d..e2d007c3 100644
--- a/doc/book/connect/apps/index.md
+++ b/doc/book/connect/apps/index.md
@@ -13,7 +13,7 @@ In this section, we cover the following web applications:
 | [Matrix](#matrix)     | ✅       |  Tested with `synapse-s3-storage-provider`    |
 | [Pixelfed](#pixelfed)     | ❓       |  Not yet tested    |
 | [Pleroma](#pleroma)     | ❓       |  Not yet tested    |
-| [Lemmy](#lemmy)     | ❓       |  Not yet tested    |
+| [Lemmy](#lemmy)     | ✅        |  Supported with pict-rs    |
 | [Funkwhale](#funkwhale)     | ❓       | Not yet tested     |
 | [Misskey](#misskey)     | ❓       | Not yet tested     |
 | [Prismo](#prismo)     | ❓       | Not yet tested     |
@@ -484,7 +484,68 @@ And add a new line. For example, to run it every 10 minutes:
 
 ## Lemmy
 
-Lemmy uses pict-rs that [supports S3 backends](https://git.asonix.dog/asonix/pict-rs/commit/f9f4fc63d670f357c93f24147c2ee3e1278e2d97)
+Lemmy uses pict-rs that [supports S3 backends](https://git.asonix.dog/asonix/pict-rs/commit/f9f4fc63d670f357c93f24147c2ee3e1278e2d97).
+This feature requires `pict-rs >= 4.0.0`.
+
+### Creating your bucket
+
+This is the usual Garage setup:
+
+```bash
+garage key new --name pictrs-key
+garage bucket create pictrs-data
+garage bucket allow pictrs-data --read --write --key pictrs-key
+```
+
+Note the Key ID and Secret Key.
+
+### Migrating your data
+
+If your pict-rs instance holds existing data, you first need to migrate to the S3 bucket.
+
+Stop pict-rs, then run the migration utility from local filesystem to the bucket:
+
+```
+pict-rs \
+  filesystem -p /path/to/existing/files \
+  object-store \
+   -e my-garage-instance.mydomain.tld:3900 \
+   -b pictrs-data \
+   -r garage \
+   -a GK... \
+   -s abcdef0123456789...
+```
+
+This is pretty slow, so hold on while migrating.
+
+### Running pict-rs with an S3 backend
+
+Pict-rs supports both a configuration file and environment variables.
+
+Either set the following section in your `pict-rs.toml`:
+
+```
+[store]
+type = 'object_storage'
+endpoint = 'http://my-garage-instance.mydomain.tld:3900'
+bucket_name = 'pictrs-data'
+region = 'garage'
+access_key = 'GK...'
+secret_key = 'abcdef0123456789...'
+```
+
+... or set these environment variables:
+
+
+```
+PICTRS__STORE__TYPE=object_storage
+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...
+PICTRS__STORE__SECRET_KEY=abcdef0123456789...
+```
+
 
 ## Funkwhale
 
diff --git a/doc/book/connect/backup.md b/doc/book/connect/backup.md
index 919e78c3..97a89e36 100644
--- a/doc/book/connect/backup.md
+++ b/doc/book/connect/backup.md
@@ -13,7 +13,41 @@ Borg Backup is very popular among the backup tools but it is not yet compatible
 We recommend using any other tool listed in this guide because they are all compatible with the S3 API.
 If you still want to use Borg, you can use it with `rclone mount`.
 
+## git-annex
 
+[git-annex](https://git-annex.branchable.com/) supports synchronizing files
+with its [S3 special remote](https://git-annex.branchable.com/special_remotes/S3/).
+
+Note that `git-annex` requires to be compiled with Haskell package version
+`aws-0.24` to work with Garage.
+
+```bash
+garage key new --name my-key
+garage bucket create my-git-annex
+garage bucket allow my-git-annex --read --write --key my-key
+```
+
+Register your Key ID and Secret key in your environment:
+
+```bash
+export AWS_ACCESS_KEY_ID=GKxxx
+export AWS_SECRET_ACCESS_KEY=xxxx
+```
+
+Within a git-annex enabled repository, configure your Garage S3 endpoint with
+the following command:
+
+```bash
+git annex initremote garage type=S3 encryption=none host=my-garage-instance.mydomain.tld protocol=https bucket=my-git-annex requeststyle=path region=garage signature=v4
+```
+
+Files can now be synchronized using the usual `git-annex` `copy` or `get`
+commands.
+
+Note that for simplicity - this example does not enable encryption for the files
+sent to Garage - please refer to the
+[git-annex encryption page](https://git-annex.branchable.com/encryption/) for
+how to configure this.
 
 ## Restic
 
diff --git a/doc/book/connect/cli.md b/doc/book/connect/cli.md
index 74e2d7ed..591ac151 100644
--- a/doc/book/connect/cli.md
+++ b/doc/book/connect/cli.md
@@ -12,6 +12,7 @@ These tools are particularly suitable for debug, backups, website deployments or
 | [AWS CLI](#aws-cli)     | ✅       | Recommended   |
 | [rclone](#rclone)     | ✅       |    |
 | [s3cmd](#s3cmd)     | ✅       |    |
+| [s5cmd](#s5cmd)     | ✅       |    |
 | [(Cyber)duck](#cyberduck)     | ✅       |    |
 | [WinSCP (libs3)](#winscp)     | ✅       | CLI instructions only   |
 | [sftpgo](#sftpgo)     | ✅       |    |
@@ -178,59 +179,34 @@ s3cmd put /tmp/hello.txt s3://my-bucket/
 s3cmd get s3://my-bucket/hello.txt hello.txt
 ```
 
-## Cyberduck & duck {#cyberduck}
+## `s5cmd`
 
-Both Cyberduck (the GUI) and duck (the CLI) have a concept of "Connection Profiles" that contain some presets for a specific provider.
-We wrote the following connection profile for Garage:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-    <dict>
-        <key>Protocol</key>
-        <string>s3</string>
-        <key>Vendor</key>
-        <string>garage</string>
-        <key>Scheme</key>
-        <string>https</string>
-        <key>Description</key>
-        <string>GarageS3</string>
-        <key>Default Hostname</key>
-        <string>127.0.0.1</string>
-        <key>Default Port</key>
-        <string>4443</string>
-        <key>Hostname Configurable</key>
-        <false/>
-        <key>Port Configurable</key>
-        <false/>
-        <key>Username Configurable</key>
-        <true/>
-        <key>Username Placeholder</key>
-        <string>Access Key ID (GK...)</string>
-        <key>Password Placeholder</key>
-        <string>Secret Key</string>
-        <key>Properties</key>
-        <array>
-            <string>s3service.disable-dns-buckets=true</string>
-        </array>
-        <key>Region</key>
-        <string>garage</string>
-        <key>Regions</key>
-        <array>
-            <string>garage</string>
-        </array>
-    </dict>
-</plist>
+Configure a credentials file as follows:
+
+```bash
+export AWS_ACCESS_KEY_ID=GK...
+export AWS_SECRET_ACCESS_KEY=
+export AWS_DEFAULT_REGION='garage'
+export AWS_ENDPOINT='http://localhost:3900'
 ```
 
-*Note: If your garage instance is configured with vhost access style, you can remove `s3service.disable-dns-buckets=true`.*
+After adding these environment variables in your shell, `s5cmd` can be used
+with:
 
-### Instructions for the GUI
+```bash
+s5cmd --endpoint-url=$AWS_ENDPOINT ls
+```
+
+See its usage output for other commands available.
+
+## Cyberduck & duck {#cyberduck}
+
+Both Cyberduck (the GUI) and duck (the CLI) have a concept of "Connection Profiles" that contain some presets for a specific provider.
 
-Copy the connection profile, and save it anywhere as `garage.cyberduckprofile`.
-Then find this file with your file explorer and double click on it: Cyberduck will open a connection wizard for this profile.
-Simply follow the wizard and you should be done!
+Within Cyberduck, a
+[Garage connection profile](https://docs.cyberduck.io/protocols/s3/garage/) is
+available within the `Preferences -> Profiles` section. This can enabled and
+then connections to Garage may be configured.
 
 ### Instuctions for the CLI
 
diff --git a/doc/book/connect/observability.md b/doc/book/connect/observability.md
new file mode 100644
index 00000000..c5037fa4
--- /dev/null
+++ b/doc/book/connect/observability.md
@@ -0,0 +1,57 @@
++++
+title = "Observability"
+weight = 25
++++
+
+An object store can be used as data storage location for metrics, and logs which
+can then be leveraged for systems observability.
+
+## Metrics
+
+### Prometheus
+
+Prometheus itself has no object store capabilities, however two projects exist
+which support storing metrics in an object store:
+
+ - [Cortex](https://cortexmetrics.io/)
+ - [Thanos](https://thanos.io/)
+
+## System logs
+
+### Vector
+
+[Vector](https://vector.dev/) natively supports S3 as a
+[data sink](https://vector.dev/docs/reference/configuration/sinks/aws_s3/)
+(and [source](https://vector.dev/docs/reference/configuration/sources/aws_s3/)).
+
+This can be configured with Garage with the following:
+
+```bash
+garage key new --name vector-system-logs
+garage bucket create system-logs
+garage bucket allow system-logs --read --write --key vector-system-logs
+```
+
+The `vector.toml` can then be configured as follows:
+
+```toml
+[sources.journald]
+type = "journald"
+current_boot_only = true
+
+[sinks.out]
+encoding.codec = "json"
+type = "aws_s3"
+inputs = [ "journald" ]
+bucket = "system-logs"
+key_prefix = "%F/"
+compression = "none"
+region = "garage"
+endpoint = "https://my-garage-instance.mydomain.tld"
+auth.access_key_id = ""
+auth.secret_access_key = ""
+```
+
+This is an example configuration - please refer to the Vector documentation for
+all configuration and transformation possibilities. Also note that Garage
+performs its own compression, so this should be disabled in Vector.