Merge pull request 'Garage v1.0' (#683) from next-0.10 into main

Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/683

3 files changed, 46 insertions, 23 deletions

diff --git a/doc/book/cookbook/encryption.md b/doc/book/cookbook/encryption.md
index 21a5cbc6..bfbea0ec 100644
--- a/doc/book/cookbook/encryption.md
+++ b/doc/book/cookbook/encryption.md
@@ -53,20 +53,43 @@ and that's also why your nodes have super long identifiers.
 
 Adding TLS support built into Garage is not currently planned.
 
-## Garage stores data in plain text on the filesystem
-
-Garage does not handle data encryption at rest by itself, and instead delegates
-to the user to add encryption, either at the storage layer (LUKS, etc) or on
-the client side (or both). There are no current plans to add data encryption
-directly in Garage.
-
-Implementing data encryption directly in Garage might make things simpler for
-end users, but also raises many more questions, especially around key
-management: for encryption of data, where could Garage get the encryption keys
-from ? If we encrypt data but keep the keys in a plaintext file next to them,
-it's useless. We probably don't want to have to manage secrets in garage as it
-would be very hard to do in a secure way. Maybe integrate with an external
-system such as Hashicorp Vault?
+## Garage stores data in plain text on the filesystem or encrypted using customer keys (SSE-C)
+
+For standard S3 API requests, Garage does not encrypt data at rest by itself.
+For the most generic at rest encryption of data, we recommend setting up your
+storage partitions on encrypted LUKS devices.
+
+If you are developping your own client software that makes use of S3 storage,
+we recommend implementing data encryption directly on the client side and never
+transmitting plaintext data to Garage. This makes it easy to use an external
+untrusted storage provider if necessary.
+
+Garage does support [SSE-C
+encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ServerSideEncryptionCustomerKeys.html),
+an encryption mode of Amazon S3 where data is encrypted at rest using
+encryption keys given by the client.  The encryption keys are passed to the
+server in a header in each request, to encrypt or decrypt data at the moment of
+reading or writing. The server discards the key as soon as it has finished
+using it for the request.  This mode allows the data to be encrypted at rest by
+Garage itself, but it requires support in the client software. It is also not
+adapted to a model where the server is not trusted or assumed to be
+compromised, as the server can easily know the encryption keys.  Note however
+that when using SSE-C encryption, the only Garage node that knows the
+encryption key passed in a given request is the node to which the request is
+directed (which can be a gateway node), so it is easy to have untrusted nodes
+in the cluster as long as S3 API requests containing SSE-C encryption keys are
+not directed to them.
+
+Implementing automatic data encryption directly in Garage without client-side
+management of keys (something like
+[SSE-S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html))
+could make things simpler for end users that don't want to setup LUKS, but also
+raises many more questions, especially around key management: for encryption of
+data, where could Garage get the encryption keys from? If we encrypt data but
+keep the keys in a plaintext file next to them, it's useless. We probably don't
+want to have to manage secrets in Garage as it would be very hard to do in a
+secure way. At the time of speaking, there are no plans to implement this in
+Garage.
 
 
 # Adding data encryption using external tools
diff --git a/doc/book/cookbook/from-source.md b/doc/book/cookbook/from-source.md
index 0d7d8e77..7105c999 100644
--- a/doc/book/cookbook/from-source.md
+++ b/doc/book/cookbook/from-source.md
@@ -91,6 +91,5 @@ The following feature flags are available in v0.8.0:
 | `metrics` | *by default* | Enable collection of metrics in Prometheus format on the admin API |
 | `telemetry-otlp` | optional | Enable collection of execution traces using OpenTelemetry |
 | `syslog` | optional | Enable logging to Syslog |
-| `sled` | *by default* | Enable using Sled to store Garage's metadata |
 | `lmdb` | *by default* | Enable using LMDB to store Garage's metadata |
 | `sqlite` | *by default* | Enable using Sqlite3 to store Garage's metadata |
diff --git a/doc/book/cookbook/real-world.md b/doc/book/cookbook/real-world.md
index 894f3db4..7dba784d 100644
--- a/doc/book/cookbook/real-world.md
+++ b/doc/book/cookbook/real-world.md
@@ -89,20 +89,21 @@ to store 2 TB of data in total.
 
 - If you only have an HDD and no SSD, it's fine to put your metadata alongside
   the data on the same drive, but then consider your filesystem choice wisely
-  (see above).  Having lots of RAM for your kernel to cache the metadata will
-  help a lot with performance.
+  (see above). Having lots of RAM for your kernel to cache the metadata will
+  help a lot with performance.  The default LMDB database engine is the most
+  tested and has good performance.
 
 ## Get a Docker image
 
 Our docker image is currently named `dxflrs/garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated).
-We encourage you to use a fixed tag (eg. `v0.9.4`) and not the `latest` tag.
-For this example, we will use the latest published version at the time of the writing which is `v0.9.4` but it's up to you
+We encourage you to use a fixed tag (eg. `v1.0.0`) and not the `latest` tag.
+For this example, we will use the latest published version at the time of the writing which is `v1.0.0` but it's up to you
 to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated).
 
 For example:
 
 ```
-sudo docker pull dxflrs/garage:v0.9.4
+sudo docker pull dxflrs/garage:v1.0.0
 ```
 
 ## Deploying and configuring Garage
@@ -127,7 +128,7 @@ data_dir = "/var/lib/garage/data"
 db_engine = "lmdb"
 metadata_auto_snapshot_interval = "6h"
 
-replication_mode = "3"
+replication_factor = 3
 
 compression_level = 2
 
@@ -168,7 +169,7 @@ docker run \
   -v /etc/garage.toml:/etc/garage.toml \
   -v /var/lib/garage/meta:/var/lib/garage/meta \
   -v /var/lib/garage/data:/var/lib/garage/data \
-  dxflrs/garage:v0.9.4
+  dxflrs/garage:v1.0.0
 ```
 
 With this command line, Garage should be started automatically at each boot.
@@ -182,7 +183,7 @@ If you want to use `docker-compose`, you may use the following `docker-compose.y
 version: "3"
 services:
   garage:
-    image: dxflrs/garage:v0.9.4
+    image: dxflrs/garage:v1.0.0
     network_mode: "host"
     restart: unless-stopped
     volumes: