aboutsummaryrefslogtreecommitdiff
path: root/doc/book
diff options
context:
space:
mode:
authorAlex Auvolat <alex@adnab.me>2024-03-04 15:56:10 +0100
committerAlex Auvolat <alex@adnab.me>2024-03-04 15:56:10 +0100
commitbbde9bc91225ac41ea6e8def61c5b7044bb186a0 (patch)
tree6e2bb951b1efb104c61d6e56aae84d7a6b036342 /doc/book
parentd0d95fd53f3d4a6fd5adcfbb4cbb031826fd64a4 (diff)
parent3168bb34a0082480660e945f7390a5ecab26c665 (diff)
downloadgarage-bbde9bc91225ac41ea6e8def61c5b7044bb186a0.tar.gz
garage-bbde9bc91225ac41ea6e8def61c5b7044bb186a0.zip
Merge branch 'main' into next-0.10
Diffstat (limited to 'doc/book')
-rw-r--r--doc/book/connect/backup.md4
-rw-r--r--doc/book/cookbook/real-world.md10
-rw-r--r--doc/book/quick-start/_index.md3
-rw-r--r--doc/book/reference-manual/configuration.md10
-rw-r--r--doc/book/reference-manual/features.md22
5 files changed, 29 insertions, 20 deletions
diff --git a/doc/book/connect/backup.md b/doc/book/connect/backup.md
index 585ec469..f39cc3b6 100644
--- a/doc/book/connect/backup.md
+++ b/doc/book/connect/backup.md
@@ -55,8 +55,8 @@ Create your key and bucket:
```bash
garage key create my-key
-garage bucket create backup
-garage bucket allow backup --read --write --key my-key
+garage bucket create backups
+garage bucket allow backups --read --write --key my-key
```
Then register your Key ID and Secret key in your environment:
diff --git a/doc/book/cookbook/real-world.md b/doc/book/cookbook/real-world.md
index ce0abddd..c15ea384 100644
--- a/doc/book/cookbook/real-world.md
+++ b/doc/book/cookbook/real-world.md
@@ -85,14 +85,14 @@ to store 2 TB of data in total.
## 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.1`) 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.1` but it's up to you
+We encourage you to use a fixed tag (eg. `v0.9.3`) 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.3` 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.1
+sudo docker pull dxflrs/garage:v0.9.3
```
## Deploying and configuring Garage
@@ -157,7 +157,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.1
+ dxflrs/garage:v0.9.3
```
With this command line, Garage should be started automatically at each boot.
@@ -171,7 +171,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.1
+ image: dxflrs/garage:v0.9.3
network_mode: "host"
restart: unless-stopped
volumes:
diff --git a/doc/book/quick-start/_index.md b/doc/book/quick-start/_index.md
index acfefb07..f359843d 100644
--- a/doc/book/quick-start/_index.md
+++ b/doc/book/quick-start/_index.md
@@ -79,8 +79,9 @@ index = "index.html"
api_bind_addr = "[::]:3904"
[admin]
-api_bind_addr = "0.0.0.0:3903"
+api_bind_addr = "[::]:3903"
admin_token = "$(openssl rand -base64 32)"
+metrics_token = "$(openssl rand -base64 32)"
EOF
```
diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md
index f1474613..af7690f4 100644
--- a/doc/book/reference-manual/configuration.md
+++ b/doc/book/reference-manual/configuration.md
@@ -69,8 +69,8 @@ root_domain = ".web.garage"
[admin]
api_bind_addr = "0.0.0.0:3903"
-metrics_token = "cacce0b2de4bc2d9f5b5fdff551e01ac1496055aed248202d415398987e35f81"
-admin_token = "ae8cb40ea7368bbdbb6430af11cca7da833d3458a5f52086f4e805a570fb5c2a"
+metrics_token = "BCAdFjoa9G0KJR0WXnHHm7fs1ZAbfpI8iIZ+Z/a2NgI="
+admin_token = "UkLeGWEvHnXBqnueR3ISEMWpOnm40jH2tM2HnnL/0F4="
trace_sink = "http://localhost:4317"
```
@@ -417,7 +417,7 @@ the node, even in the case of a NAT: the NAT should be configured to forward the
port number to the same internal port nubmer. This means that if you have several nodes running
behind a NAT, they should each use a different RPC port number.
-#### `rpc_bind_outgoing` {#rpc_bind_outgoing} (since v0.9.2)
+#### `rpc_bind_outgoing`(since v0.9.2) {#rpc_bind_outgoing}
If enabled, pre-bind all sockets for outgoing connections to the same IP address
used for listening (the IP address specified in `rpc_bind_addr`) before
@@ -612,7 +612,7 @@ the socket will have 0220 mode. Make sure to set user and group permissions acco
The token for accessing the Metrics endpoint. If this token is not set, the
Metrics endpoint can be accessed without access control.
-You can use any random string for this value. We recommend generating a random token with `openssl rand -hex 32`.
+You can use any random string for this value. We recommend generating a random token with `openssl rand -base64 32`.
`metrics_token` was introduced in Garage `v0.7.2`.
`metrics_token_file` and the `GARAGE_METRICS_TOKEN` environment variable are supported since Garage `v0.8.2`.
@@ -624,7 +624,7 @@ You can use any random string for this value. We recommend generating a random t
The token for accessing all of the other administration endpoints. If this
token is not set, access to these endpoints is disabled entirely.
-You can use any random string for this value. We recommend generating a random token with `openssl rand -hex 32`.
+You can use any random string for this value. We recommend generating a random token with `openssl rand -base64 32`.
`admin_token` was introduced in Garage `v0.7.2`.
`admin_token_file` and the `GARAGE_ADMIN_TOKEN` environment variable are supported since Garage `v0.8.2`.
diff --git a/doc/book/reference-manual/features.md b/doc/book/reference-manual/features.md
index e8ba9510..f7014b26 100644
--- a/doc/book/reference-manual/features.md
+++ b/doc/book/reference-manual/features.md
@@ -37,6 +37,21 @@ A Garage cluster can very easily evolve over time, as storage nodes are added or
Garage will automatically rebalance data between nodes as needed to ensure the desired number of copies.
Read about cluster layout management [here](@/documentation/operations/layout.md).
+### Several replication modes
+
+Garage supports a variety of replication modes, with 1 copy, 2 copies or 3 copies of your data,
+and with various levels of consistency, in order to adapt to a variety of usage scenarios.
+Read our reference page on [supported replication modes](@/documentation/reference-manual/configuration.md#replication_mode)
+to select the replication mode best suited to your use case (hint: in most cases, `replication_mode = "3"` is what you want).
+
+### Compression and deduplication
+
+All data stored in Garage is deduplicated, and optionnally compressed using
+Zstd. Objects uploaded to Garage are chunked in blocks of constant sizes (see
+[`block_size`](@/documentation/reference-manual/configuration.md#block_size)),
+and the hashes of individual blocks are used to dispatch them to storage nodes
+and to deduplicate them.
+
### No RAFT slowing you down
It might seem strange to tout the absence of something as a desirable feature,
@@ -48,13 +63,6 @@ As a consequence, requests can be handled much faster, even in cases where laten
between cluster nodes is important (see our [benchmarks](@/documentation/design/benchmarks/index.md) for data on this).
This is particularly usefull when nodes are far from one another and talk to one other through standard Internet connections.
-### Several replication modes
-
-Garage supports a variety of replication modes, with 1 copy, 2 copies or 3 copies of your data,
-and with various levels of consistency, in order to adapt to a variety of usage scenarios.
-Read our reference page on [supported replication modes](@/documentation/reference-manual/configuration.md#replication_mode)
-to select the replication mode best suited to your use case (hint: in most cases, `replication_mode = "3"` is what you want).
-
### Web server for static websites
A storage bucket can easily be configured to be served directly by Garage as a static web site.