Merge branch 'main' into next

2026-08-31 09:18:29 +00:00 · 2023-04-25 12:34:26 +02:00
parent 654999e254 a16eb7e4b8
commit fa78d806e3
202 changed files with 25943 additions and 2775 deletions
@@ -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

@@ -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

@@ -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

@@ -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
 ```

+## `s5cmd`
+
+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'
+```
+
+After adding these environment variables in your shell, `s5cmd` can be used
+with:
+
+```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.
-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>
-```
-
-*Note: If your garage instance is configured with vhost access style, you can remove `s3service.disable-dns-buckets=true`.*
-
-### Instructions for the GUI
-
-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

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