From 4ae03aa774c72a67316853895de2b708f1db6cf4 Mon Sep 17 00:00:00 2001 From: Alex Date: Thu, 10 Feb 2022 15:58:09 +0100 Subject: Small documentation updates (#237) Fixes #234, among other things Co-authored-by: Alex Auvolat Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/237 Co-authored-by: Alex Co-committed-by: Alex --- doc/book/development/release-process.md | 3 ++- doc/book/quick-start/_index.md | 2 +- doc/book/reference-manual/configuration.md | 36 +++++++++++++++++------------- 3 files changed, 23 insertions(+), 18 deletions(-) diff --git a/doc/book/development/release-process.md b/doc/book/development/release-process.md index eee45e24..f6db971a 100644 --- a/doc/book/development/release-process.md +++ b/doc/book/development/release-process.md @@ -32,9 +32,10 @@ We generate the following binary artifacts for now: - **os**: linux - **format**: static binary, docker container -Additionnaly we also build two web pages: +Additionnaly we also build two web pages and one JSON document: - the documentation (this website) - [the release page](https://garagehq.deuxfleurs.fr/_releases.html) + - [the release list in JSON format](https://garagehq.deuxfleurs.fr/_releases.json) We publish the static binaries on our own garage cluster (you can access them through the releases page) and the docker containers on Docker Hub. diff --git a/doc/book/quick-start/_index.md b/doc/book/quick-start/_index.md index cd916bda..025747bc 100644 --- a/doc/book/quick-start/_index.md +++ b/doc/book/quick-start/_index.md @@ -20,7 +20,7 @@ as it provides no redundancy for your data! Download the latest Garage binary from the release pages on our repository: - + Place this binary somewhere in your `$PATH` so that you can invoke the `garage` command directly (for instance you can copy the binary in `/usr/local/bin` diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md index 662b00f9..a5ee3a3c 100644 --- a/doc/book/reference-manual/configuration.md +++ b/doc/book/reference-manual/configuration.md @@ -40,7 +40,6 @@ root_domain = ".s3.garage" [s3_web] bind_addr = "[::]:3902" root_domain = ".web.garage" -index = "index.html" ``` The following gives details about each available configuration option. @@ -60,19 +59,22 @@ Store this folder on a fast SSD drive if possible to maximize Garage's performan The directory in which Garage will store the data blocks of objects. This folder can be placed on an HDD. The space available for `data_dir` should be counted to determine a node's capacity -when [configuring it](@/documentation/cookbook/real-world.md). +when [adding it to the cluster layout](@/documentation/cookbook/real-world.md). ### `block_size` Garage splits stored objects in consecutive chunks of size `block_size` (except the last one which might be smaller). The default size is 1MB and -should work in most cases. If you are interested in tuning this, feel free -to do so (and remember to report your findings to us!). If this value is -changed for a running Garage installation, only files newly uploaded will be -affected. Previously uploaded files will remain available. This however -means that chunks from existing files will not be deduplicated with chunks -from newly uploaded files, meaning you might use more storage space that is -optimally possible. +should work in most cases. We recommend increasing it to e.g. 10MB if +you are using Garage to store large files and have fast network connections +between all nodes (e.g. 1gbps). + +If you are interested in tuning this, feel free to do so (and remember to +report your findings to us!). When this value is changed for a running Garage +installation, only files newly uploaded will be affected. Previously uploaded +files will remain available. This however means that chunks from existing files +will not be deduplicated with chunks from newly uploaded files, meaning you +might use more storage space that is optimally possible. ### `replication_mode` @@ -114,12 +116,12 @@ default value (currently `3`). Finally, zstd has also compression designed to be than default compression levels, they range from `-1` (smaller file) to `-99` (faster compression). -If you do not specify a `compression_level` entry, garage will set it to `1` for you. With +If you do not specify a `compression_level` entry, Garage will set it to `1` for you. With this parameters, zstd consumes low amount of cpu and should work faster than line speed in most situations, while saving some space and intra-cluster bandwidth. -If you want to totally deactivate zstd in garage, you can pass the special value `'none'`. No +If you want to totally deactivate zstd in Garage, you can pass the special value `'none'`. No zstd related code will be called, your chunks will be stored on disk without any processing. Compression is done synchronously, setting a value too high will add latency to write queries. @@ -169,21 +171,23 @@ yourself. ### `consul_host` and `consul_service_name` -Garage supports discovering other nodes of the cluster using Consul. -This works only when nodes are announced in Consul by an orchestrator such as Nomad, -as Garage is not able to announce itself. +Garage supports discovering other nodes of the cluster using Consul. For this +to work correctly, nodes need to know their IP address by which they can be +reached by other nodes of the cluster, which should be set in `rpc_public_addr`. The `consul_host` parameter should be set to the hostname of the Consul server, and `consul_service_name` should be set to the service name under which Garage's RPC ports are announced. +Garage does not yet support talking to Consul over TLS. + ### `sled_cache_capacity` This parameter can be used to tune the capacity of the cache used by [sled](https://sled.rs), the database Garage uses internally to store metadata. Tune this to fit the RAM you wish to make available to your Garage instance. -More cache means faster Garage, but the default value (128MB) should be plenty -for most use cases. +This value has a conservative default (128MB) so that Garage doesn't use too much +RAM by default, but feel free to increase this for higher performance. ### `sled_flush_every_ms` -- cgit v1.2.3