diff options
Diffstat (limited to 'doc/book/src/cookbook')
| -rw-r--r-- | doc/book/src/cookbook/clients.md | 13 | ||||
| -rw-r--r-- | doc/book/src/cookbook/from_source.md | 51 | ||||
| -rw-r--r-- | doc/book/src/cookbook/index.md | 20 | ||||
| -rw-r--r-- | doc/book/src/cookbook/real_world.md | 272 | ||||
| -rw-r--r-- | doc/book/src/cookbook/systemd.md | 39 | ||||
| -rw-r--r-- | doc/book/src/cookbook/website.md | 2 |
6 files changed, 396 insertions, 1 deletions
diff --git a/doc/book/src/cookbook/clients.md b/doc/book/src/cookbook/clients.md new file mode 100644 index 00000000..006f604a --- /dev/null +++ b/doc/book/src/cookbook/clients.md @@ -0,0 +1,13 @@ +# Configuring S3 clients to interact with Garage + +## AWS CLI + +## Minio client + +## `rclone` + +## Cyberduck + +## `s3cmd` + + diff --git a/doc/book/src/cookbook/from_source.md b/doc/book/src/cookbook/from_source.md new file mode 100644 index 00000000..167f01db --- /dev/null +++ b/doc/book/src/cookbook/from_source.md @@ -0,0 +1,51 @@ +# Compiling Garage from source + + +Garage is a standard Rust project. +First, you need `rust` and `cargo`. +For instance on Debian: + +```bash +sudo apt-get update +sudo apt-get install -y rustc cargo +``` + +You can also use [Rustup](https://rustup.rs/) to setup a Rust toolchain easily. + +## Using source from `crates.io` + +Garage's source code is published on `crates.io`, Rust's official package repository. +This means you can simply ask `cargo` to download and build this source code for you: + +```bash +cargo install garage +``` + +That's all, `garage` should be in `$HOME/.cargo/bin`. + +You can add this folder to your `$PATH` or copy the binary somewhere else on your system. +For instance: + +```bash +sudo cp $HOME/.cargo/bin/garage /usr/local/bin/garage +``` + + +## Using source from the Gitea repository + +The primary location for Garage's source code is the +[Gitea repository](https://git.deuxfleurs.fr/Deuxfleurs/garage). + +Clone the repository and build Garage with the following commands: + +```bash +git clone https://git.deuxfleurs.fr/Deuxfleurs/garage.git +cd garage +cargo build +``` + +Be careful, as this will make a debug build of Garage, which will be extremely slow! +To make a release build, invoke `cargo build --release` (this takes much longer). + +The binaries built this way are found in `target/{debug,release}/garage`. + diff --git a/doc/book/src/cookbook/index.md b/doc/book/src/cookbook/index.md index 26ec68bb..a838b549 100644 --- a/doc/book/src/cookbook/index.md +++ b/doc/book/src/cookbook/index.md @@ -3,3 +3,23 @@ A cookbook, when you cook, is a collection of recipes. Similarly, Garage's cookbook contains a collection of recipes that are known to works well! This chapter could also be referred as "Tutorials" or "Best practices". + +- **[Deploying Garage](real_world.md):** This page will walk you through all of the necessary + steps to deploy Garaage in a real-world setting. + +- **[Configuring S3 clients](clients.md):** This page will explain how to configure + popular S3 clients to interact with a Garage server. + +- **[Hosting a website](website.md):** This page explains how to use Garage + to host a static website. + +- **[Recovering from failures](recovering.md):** Garage's first selling point is resilience + to hardware failures. This section explains how to recover from such a failure in the + best possible way. + +- **[Building from source](from_source.md):** This page explains how to build Garage from + source in case a binary is not provided for your architecture, or if you want to + hack with us! + +- **[Starting with Systemd](from_source.md):** This page explains how to run Garage + as a Systemd service (instead of as a Docker container). diff --git a/doc/book/src/cookbook/real_world.md b/doc/book/src/cookbook/real_world.md new file mode 100644 index 00000000..abef8912 --- /dev/null +++ b/doc/book/src/cookbook/real_world.md @@ -0,0 +1,272 @@ +# Deploying Garage on a real-world cluster + +To run Garage in cluster mode, we recommend having at least 3 nodes. +This will allow you to setup Garage for three-way replication of your data, +the safest and most available mode avaialble. + +We recommend first following the [quick start guide](../quick_start/index.md) in order +to get familiar with Garage's command line and usage patterns. + +## Get a Docker image + +Our docker image is currently named `lxpz/garage_amd64` and is stored on the [Docker Hub](https://hub.docker.com/r/lxpz/garage_amd64/tags?page=1&ordering=last_updated). +We encourage you to use a fixed tag (eg. `v0.3.0`) and not the `latest` tag. +For this example, we will use the latest published version at the time of the writing which is `v0.3.0` but it's up to you +to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/lxpz/garage_amd64/tags?page=1&ordering=last_updated). + +For example: + +``` +sudo docker pull lxpz/garage_amd64:v0.3.0 +``` + + +## Generating TLS certificates + +You first need to generate TLS certificates to encrypt traffic between Garage nodes +(reffered to as RPC traffic). + +To generate your TLS certificates, run on your machine: + +``` +wget https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/branch/main/genkeys.sh +chmod +x genkeys.sh +./genkeys.sh +``` + +It will creates a folder named `pki/` containing the keys that you will used for the cluster. + + +## Deploying and configuring Garage + +To run a real-world deployment, make sure you the following conditions are met: + +- You have at least three machines with sufficient storage space available + +- Each machine has a public IP address which is reachable by other machines. + Running behind a NAT is possible, but having several Garage nodes behind a single NAT + is slightly more involved as each will have to have a different RPC port number + (the local port number of a node must be the same as the port number exposed publicly + by the NAT). + +- Ideally, each machine should have a SSD available in addition to the HDD you are dedicating + to Garage. This will allow for faster access to metadata and has the potential + to drastically reduce Garage's response times. + +Before deploying garage on your infrastructure, you must inventory your machines. +For our example, we will suppose the following infrastructure with IPv6 connectivity: + +| Location | Name | IP Address | Disk Space | +|----------|---------|------------|------------| +| Paris | Mercury | fc00:1::1 | 1 To | +| Paris | Venus | fc00:1::2 | 2 To | +| London | Earth | fc00:B::1 | 2 To | +| Brussels | Mars | fc00:F::1 | 1.5 To | + + +On each machine, we will have a similar setup, +especially you must consider the following folders/files: + + - `/etc/garage/garage.toml`: Garage daemon's configuration (see below) + - `/etc/garage/pki/`: Folder containing Garage certificates, must be generated on your computer and copied on the servers + - `/var/lib/garage/meta/`: Folder containing Garage's metadata, put this folder on a SSD if possible + - `/var/lib/garage/data/`: Folder containing Garage's data, this folder will grows and must be on a large storage, possibly big HDDs. + - `/etc/systemd/system/garage.service`: Service file to start garage at boot automatically (defined below, not required if you use docker) + +A valid `/etc/garage/garage.toml` for our cluster would be: + +```toml +metadata_dir = "/var/lib/garage/meta" +data_dir = "/var/lib/garage/data" + +replication_mode = "3" + +rpc_bind_addr = "[::]:3901" + +bootstrap_peers = [ + "[fc00:1::1]:3901", + "[fc00:1::2]:3901", + "[fc00:B::1]:3901", + "[fc00:F::1]:3901", +] + +[rpc_tls] +ca_cert = "/etc/garage/pki/garage-ca.crt" +node_cert = "/etc/garage/pki/garage.crt" +node_key = "/etc/garage/pki/garage.key" + +[s3_api] +s3_region = "garage" +api_bind_addr = "[::]:3900" + +[s3_web] +bind_addr = "[::]:3902" +root_domain = ".web.garage" +index = "index.html" +``` + +Please make sure to change `bootstrap_peers` to **your** IP addresses! + +Check the [configuration file reference documentation](../reference_manual/configuration.md) +to learn more about all available configuration options. + + +## Starting Garage using Docker + +On each machine, you can run the daemon with: + +```bash +docker run \ + -d \ + --name garaged \ + --restart always \ + --network host \ + -v /etc/garage/pki:/etc/garage/pki \ + -v /etc/garage/garage.toml:/garage/garage.toml \ + -v /var/lib/garage/meta:/var/lib/garage/meta \ + -v /var/lib/garage/data:/var/lib/garage/data \ + lxpz/garage_amd64:v0.3.0 +``` + +It should be restart automatically at each reboot. +Please note that we use host networking as otherwise Docker containers +can not communicate with IPv6. + +Upgrading between Garage versions should be supported transparently, +but please check the relase notes before doing so! +To upgrade, simply stop and remove this container and +start again the command with a new version of garage. + + +## Controling the daemon + +The `garage` binary has two purposes: + - it acts as a daemon when launched with `garage server ...` + - it acts as a control tool for the daemon when launched with any other command + +In this section, we will see how to use the `garage` binary as a control tool for the daemon we just started. +You first need to get a shell having access to this binary. For instance, enter the Docker container with: + +```bash +sudo docker exec -ti garaged bash +``` + +You will now have a shell where the Garage binary is available as `/garage/garage` + +*You can also install the binary on your machine to remotely control the cluster.* + +## Talk to the daemon and create an alias + +`garage` requires 4 options to talk with the daemon: + +``` +--ca-cert <ca-cert> +--client-cert <client-cert> +--client-key <client-key> +-h, --rpc-host <rpc-host> +``` + +The 3 first ones are certificates and keys needed by TLS, the last one is simply the address of garage's RPC endpoint. + +If you are invoking `garage` from a server node directly, you do not need to set `--rpc-host` +as the default value `127.0.0.1:3901` will allow it to contact Garage correctly. + +To avoid typing the 3 first options each time we want to run a command, +you can use the following alias: + +```bash +alias garagectl='/garage/garage \ + --ca-cert /etc/garage/pki/garage-ca.crt \ + --client-cert /etc/garage/pki/garage.crt \ + --client-key /etc/garage/pki/garage.key' +``` + +You can now use all of the commands presented in the [quick start guide](../quick_start/index.md), +simply replace occurences of `garage` by `garagectl`. + +#### Test the alias + +You can test your alias by running a simple command such as: + +``` +garagectl status +``` + +You should get something like that as result: + +``` +Healthy nodes: +2a638ed6c775b69a… 37f0ba978d27 [::ffff:172.20.0.101]:3901 UNCONFIGURED/REMOVED +68143d720f20c89d… 9795a2f7abb5 [::ffff:172.20.0.103]:3901 UNCONFIGURED/REMOVED +8781c50c410a41b3… 758338dde686 [::ffff:172.20.0.102]:3901 UNCONFIGURED/REMOVED +``` + + +## Configuring a cluster + +We will now inform garage of the disk space available on each node of the cluster +as well as the zone (e.g. datacenter) in which each machine is located. + +For our example, we will suppose we have the following infrastructure (Capacity, Identifier and Datacenter are specific values to garage described in the following): + +| Location | Name | Disk Space | `Capacity` | `Identifier` | `Zone` | +|----------|---------|------------|------------|--------------|--------------| +| Paris | Mercury | 1 To | `2` | `8781c5` | `par1` | +| Paris | Venus | 2 To | `4` | `2a638e` | `par1` | +| London | Earth | 2 To | `4` | `68143d` | `lon1` | +| Brussels | Mars | 1.5 To | `3` | `212f75` | `bru1` | + +#### Node identifiers + +After its first launch, garage generates a random and unique identifier for each nodes, such as: + +``` +8781c50c410a41b363167e9d49cc468b6b9e4449b6577b64f15a249a149bdcbc +``` + +Often a shorter form can be used, containing only the beginning of the identifier, like `8781c5`, +which identifies the server "Mercury" located in "Paris" according to our previous table. + +The most simple way to match an identifier to a node is to run: + +``` +garagectl status +``` + +It will display the IP address associated with each node; from the IP address you will be able to recognize the node. + +#### Zones + +Zones are simply a user-chosen identifier that identify a group of server that are grouped together logically. +It is up to the system administrator deploying garage to identify what does "grouped together" means. + +In most cases, a zone will correspond to a geographical location (i.e. a datacenter). +Behind the scene, Garage will use zone definition to try to store the same data on different zones, +in order to provide high availability despite failure of a zone. + +#### Capacity + +Garage reasons on an arbitrary metric about disk storage that is named the *capacity* of a node. +The capacity configured in Garage must be proportional to the disk space dedicated to the node. +Additionaly, the capacity values used in Garage should be as small as possible, with +1 ideally representing the size of your smallest server. + +Here we chose that 1 unit of capacity = 0.5 To, so that we can express servers of size +1 To and 2 To, as wel as the intermediate size 1.5 To. + +Note that the amount of data stored by Garage on each server may not be strictly proportional to +its capacity value, as Garage will priorize having 3 copies of data in different zones, +even if this means that capacities will not be strictly respected. For example in our above examples, +nodes Earth and Mars will always store a copy of everything each, and the third copy will +have 66% chance of being stored by Venus and 33% chance of being stored by Mercury. + +#### Injecting the topology + +Given the information above, we will configure our cluster as follow: + +``` +garagectl node configure -z par1 -c 2 -t mercury 8781c5 +garagectl node configure -z par1 -c 4 -t venus 2a638e +garagectl node configure -z lon1 -c 4 -t earth 68143d +garagectl node configure -z bru1 -c 3 -t mars 212f75 +``` diff --git a/doc/book/src/cookbook/systemd.md b/doc/book/src/cookbook/systemd.md new file mode 100644 index 00000000..aded09ad --- /dev/null +++ b/doc/book/src/cookbook/systemd.md @@ -0,0 +1,39 @@ +# Starting Garage with systemd instead of Docker + +NOTE: This guide is incomplete. Typicall you would also want to create a separate +Unix user to run Garage. + +Make sure you have the Garage binary installed on your system (see [quick start](../quick_start/index.md)), e.g. at `/usr/local/bin/garage`. + +Create a file named `/etc/systemd/system/garage.service`: + +```toml +[Unit] +Description=Garage Data Store +After=network-online.target +Wants=network-online.target + +[Service] +Environment='RUST_LOG=garage=info' 'RUST_BACKTRACE=1' +ExecStart=/usr/local/bin/garage server -c /etc/garage/garage.toml + +[Install] +WantedBy=multi-user.target +``` + +To start the service then automatically enable it at boot: + +```bash +sudo systemctl start garage +sudo systemctl enable garage +``` + +To see if the service is running and to browse its logs: + +```bash +sudo systemctl status garage +sudo journalctl -u garage +``` + +If you want to modify the service file, do not forget to run `systemctl daemon-reload` +to inform `systemd` of your modifications. diff --git a/doc/book/src/cookbook/website.md b/doc/book/src/cookbook/website.md index b3dd1b51..53488ac4 100644 --- a/doc/book/src/cookbook/website.md +++ b/doc/book/src/cookbook/website.md @@ -1,3 +1,3 @@ -# Host a website +# Hosting a website TODO |