From 468e45ed7f47ce41f196274519c6b59f3bf46f0e Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Wed, 17 Mar 2021 18:01:06 +0100 Subject: [PATCH] WIP doc --- doc/book/src/getting_started/binary.md | 22 +++++++++ doc/book/src/getting_started/daemon.md | 64 +++++++++++++++++++++----- 2 files changed, 74 insertions(+), 12 deletions(-) diff --git a/doc/book/src/getting_started/binary.md b/doc/book/src/getting_started/binary.md index ba8838b6..9a18babc 100644 --- a/doc/book/src/getting_started/binary.md +++ b/doc/book/src/getting_started/binary.md @@ -19,4 +19,26 @@ sudo docker pull lxpz/garage_amd64:v0.1.1d ## From source +Garage is a standard Rust project. +First, you need `rust` and `cargo`. +On Debian: + +```bash +sudo apt-get update +sudo apt-get install -y rustc cargo +``` + +Then, you can ask cargo to install the binary 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 the following, we will assume you copied it in `/usr/local/bin/garage`: + +```bash +sudo cp $HOME/.cargo/bin/garage /usr/local/bin/garage +``` diff --git a/doc/book/src/getting_started/daemon.md b/doc/book/src/getting_started/daemon.md index d704ad0d..0f0199fe 100644 --- a/doc/book/src/getting_started/daemon.md +++ b/doc/book/src/getting_started/daemon.md @@ -2,14 +2,14 @@ Garage is a software that can be run only in a cluster and requires at least 3 instances. In our getting started guide, we document two deployment types: - - [Single machine deployment](#single-machine-deployment) though `docker-compose` - - [Multiple machine deployment](#multiple-machine-deployment) through `docker` or `systemd` + - [Test deployment](#test-deployment) though `docker-compose` + - [Real-world deployment](#real-world-deployment) through `docker` or `systemd` In any case, you first need to generate TLS certificates, as traffic is encrypted between Garage's nodes. ## Generating a TLS Certificate -Next, to generate your TLS certificates, run on your machine: +To generate your TLS certificates, run on your machine: ``` wget https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/branch/master/genkeys.sh @@ -19,9 +19,18 @@ chmod +x genkeys.sh It will creates a folder named `pki` containing the keys that you will used for the cluster. -### Single machine deployment +## Test deployment -Single machine deployment is only described through docker compose. +Single machine deployment is only described through `docker-compose`. + +Before starting, we recommend you create a folder for our deployment: + +```bash +mkdir garage-single +cd garage-single +``` + +We start by creating a file named `docker-compose.yml` describing our network and our containers: ```yml version: '3.4' @@ -54,7 +63,7 @@ services: *We define a static network here which is not considered as a best practise on Docker. The rational is that Garage only supports IP address and not domain names in its configuration, so we need to know the IP address in advance.* -and then create the `config.toml` file as follow: +and then create the `config.toml` file next to it as follow: ```toml metadata_dir = "/garage/meta" @@ -104,7 +113,9 @@ Not found Not found ``` -### Multiple machine deployment +That's all, you are ready to [configure your cluster!](./cluster.md). + +## Real-world deployment Before deploying garage on your infrastructure, you must inventory your machines. For our example, we will suppose the following infrastructure: @@ -116,8 +127,14 @@ For our example, we will suppose the following infrastructure: | London | Earth | fc00:1::2 | 2 To | | Brussels | Mars | fc00:B::1 | 1.5 To | -First, you need to setup your machines/VMs by copying on them the `pki` folder in `/etc/garage/pki`. -All your machines will also share the same configuration file, stored in `/etc/garage/config.toml`: +On each machine, we will have a similar setup, especially you must consider the following folders/files: + - `/etc/garage/pki`: Garage certificates, must be generated on your computer and copied on the servers + - `/etc/garage/config.toml`: Garage daemon's configuration (defined below) + - `/etc/systemd/system/garage.service`: Service file to start garage at boot automatically (defined below, not required if you use docker) + - `/var/lib/garage/meta`: Contains Garage's metadata, put this folder on a SSD if possible + - `/var/lib/garage/data`: Contains Garage's data, this folder will grows and must be on a large storage, possibly big HDDs. + +A valid `/etc/garage/config.toml` for our cluster would be: ```toml metadata_dir = "/var/lib/garage/meta" @@ -131,9 +148,9 @@ bootstrap_peers = [ ] [rpc_tls] -ca_cert = "/pki/garage-ca.crt" -node_cert = "/pki/garage.crt" -node_key = "/pki/garage.key" +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" @@ -145,4 +162,27 @@ root_domain = ".web.garage" index = "index.html" ``` +Please make sure to change `bootstrap_peers` to **your** IP addresses! +### For docker users + +On each machine, you can run the daemon with: + +```bash +docker run \ + -d \ + --restart always \ + --network host \ + -v /etc/garage/pki:/etc/garage/pki \ + -v /etc/garage/config.toml:/garage/config.toml \ + -v /var/lib/garage/meta:/var/lib/garage/meta \ + -v /var/lib/garage/data:/var/lib/garage/data \ + lxpz/garage_amd64:v0.1.1d +``` + +It should be restart automatically at each reboot. +Please note that we use host networking as otherwise Docker containers can no communicate with IPv6. + +To upgrade, simply stop and remove this container and start again the command with a new version of garage. + +### For systemd/raw binary users