From 60f994a118afdde241d9a2296e2e8e090e08674d Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Wed, 17 Mar 2021 17:24:11 +0100 Subject: [PATCH] Working on the getting started guide --- doc/book/src/SUMMARY.md | 3 +- doc/book/src/cookbook/index.md | 4 + doc/book/src/design/index.md | 4 + doc/book/src/development/index.md | 3 + .../getting_started/{install.md => binary.md} | 17 +- doc/book/src/getting_started/daemon.md | 148 ++++++++++++++++++ doc/book/src/reference_manual/index.md | 4 + doc/book/src/working_documents/index.md | 7 +- .../src/working_documents/load_balancing.md | 2 +- 9 files changed, 177 insertions(+), 15 deletions(-) rename doc/book/src/getting_started/{install.md => binary.md} (64%) create mode 100644 doc/book/src/getting_started/daemon.md diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md index 7697948b..48abf741 100644 --- a/doc/book/src/SUMMARY.md +++ b/doc/book/src/SUMMARY.md @@ -3,7 +3,8 @@ [The Garage Data Store](./intro.md) - [Getting Started](./getting_started/index.md) - - [Installation](./getting_started/install.md) + - [Get a binary](./getting_started/binary.md) + - [Configure the daemon](./getting_started/daemon.md) - [Configure a cluster](./getting_started/cluster.md) - [Create buckets and keys](./getting_started/bucket.md) - [Handle files](./getting_started/files.md) diff --git a/doc/book/src/cookbook/index.md b/doc/book/src/cookbook/index.md index 741ecbe7..d7a51065 100644 --- a/doc/book/src/cookbook/index.md +++ b/doc/book/src/cookbook/index.md @@ -1 +1,5 @@ # Cookbook + +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 practises". diff --git a/doc/book/src/design/index.md b/doc/book/src/design/index.md index 3d14cb7c..d09a6008 100644 --- a/doc/book/src/design/index.md +++ b/doc/book/src/design/index.md @@ -1 +1,5 @@ # Design + +The design section helps you to see Garage from a "big picture" perspective. +It will allow you to understand if Garage is a good fit for you, +how to better use it, how to contribute to it, what can Garage could and could not do, etc. diff --git a/doc/book/src/development/index.md b/doc/book/src/development/index.md index 459110d3..d6b5e38b 100644 --- a/doc/book/src/development/index.md +++ b/doc/book/src/development/index.md @@ -1 +1,4 @@ # Development + +Now that you are a Garage expert, you want to enhance it, you are in the right place! +We discuss here how to hack on Garage, how we manage its development, etc. diff --git a/doc/book/src/getting_started/install.md b/doc/book/src/getting_started/binary.md similarity index 64% rename from doc/book/src/getting_started/install.md rename to doc/book/src/getting_started/binary.md index 98af1283..ba8838b6 100644 --- a/doc/book/src/getting_started/install.md +++ b/doc/book/src/getting_started/binary.md @@ -1,4 +1,4 @@ -# Installation +# Get a binary Currently, only two installations procedures are supported for Garage: from Docker (x86\_64 for Linux) and from source. In the future, we plan to add a third one, by publishing a compiled binary (x86\_64 for Linux). @@ -6,20 +6,17 @@ We did not test other architecture/operating system but, as long as your archite ## From Docker -Garage is a software that can be run only in a cluster and requires at least 3 instances. -If you plan to run the 3 instances on your machine for test purposes, we recommend a **docker-compose** deployment. -If you have 3 independent machines (or 3 VM on independent machines) that can communite together, a **simple docker** deployment is enough. -In any case, you first need to pick a Docker image version. - 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.1.1d`) and not the `latest` tag. For this example, we will use the latest published version at the time of the writing which is `v0.1.1d` 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). -### Single machine deployment with docker-compose +For example: - - -### Multiple machine deployment with docker +``` +sudo docker pull lxpz/garage_amd64:v0.1.1d +``` ## From source + + diff --git a/doc/book/src/getting_started/daemon.md b/doc/book/src/getting_started/daemon.md new file mode 100644 index 00000000..d704ad0d --- /dev/null +++ b/doc/book/src/getting_started/daemon.md @@ -0,0 +1,148 @@ +# Configure the daemon + +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` + +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: + +``` +wget https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/branch/master/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. + +### Single machine deployment + +Single machine deployment is only described through docker compose. + +```yml +version: '3.4' + +networks: { virtnet: { ipam: { config: [ subnet: 172.20.0.0/24 ]}}} + +services: + g1: + image: lxpz/garage_amd64:v0.1.1d + networks: { virtnet: { ipv4_address: 172.20.0.101 }} + volumes: + - "./pki:/pki" + - "./config.toml:/garage/config.toml" + + g2: + image: lxpz/garage_amd64:v0.1.1d + networks: { virtnet: { ipv4_address: 172.20.0.102 }} + volumes: + - "./pki:/pki" + - "./config.toml:/garage/config.toml" + + g3: + image: lxpz/garage_amd64:v0.1.1d + networks: { virtnet: { ipv4_address: 172.20.0.103 }} + volumes: + - "./pki:/pki" + - "./config.toml:/garage/config.toml" +``` + +*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: + +```toml +metadata_dir = "/garage/meta" +data_dir = "/garage/data" +rpc_bind_addr = "[::]:3901" +bootstrap_peers = [ + "172.20.0.101:3901", + "172.20.0.102:3901", + "172.20.0.103:3901", +] + +[rpc_tls] +ca_cert = "/pki/garage-ca.crt" +node_cert = "/pki/garage.crt" +node_key = "/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 note that we have not mounted `/garage/meta` or `/garage/data` on the host: data will be lost when the container will be destroyed.* + +And that's all, you are ready to launch your cluster! + +``` +sudo docker-compose up +``` + +While your daemons are up, your cluster is still not configured yet. +However, you can check that your services are still listening as expected by querying them from your host: + +```bash +curl http://172.20.0.{101,102,103}:3902 +``` + +which should give you: + +``` +Not found +Not found +Not found +``` + +### Multiple machine deployment + +Before deploying garage on your infrastructure, you must inventory your machines. +For our example, we will suppose the following infrastructure: + +| Location | Name | IP Address | Disk Space | +|----------|---------|------------|------------| +| Paris | Mercury | fc00:1::1 | 1 To | +| Paris | Venus | fc00:1::2 | 2 To | +| 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`: + +```toml +metadata_dir = "/var/lib/garage/meta" +data_dir = "/var/lib/garage/data" +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 = "/pki/garage-ca.crt" +node_cert = "/pki/garage.crt" +node_key = "/pki/garage.key" + +[s3_api] +s3_region = "garage" +api_bind_addr = "[::]:3900" + +[s3_web] +bind_addr = "[::]:3902" +root_domain = ".web.garage" +index = "index.html" +``` + + diff --git a/doc/book/src/reference_manual/index.md b/doc/book/src/reference_manual/index.md index a2f380f6..0d4bd6f3 100644 --- a/doc/book/src/reference_manual/index.md +++ b/doc/book/src/reference_manual/index.md @@ -1 +1,5 @@ # Reference Manual + +A reference manual contains some extensive descriptions about the features and the behaviour of the software. +Reading of this chapter is recommended once you have a good knowledge/understanding of Garage. +It will be useful if you want to tune it or to use it in some exotic conditions. diff --git a/doc/book/src/working_documents/index.md b/doc/book/src/working_documents/index.md index 6eb7eccb..a9e7f899 100644 --- a/doc/book/src/working_documents/index.md +++ b/doc/book/src/working_documents/index.md @@ -1,7 +1,8 @@ # Working Documents Working documents are documents that reflect the fact that Garage is a software that evolves quickly. -They are a way to communicate our ideas, our changes, and so on. +They are a way to communicate our ideas, our changes, and so on before or while we are implementing them in Garage. +If you like to live on the edge, it could also serve as a documentation of our next features to be released. -Ideally, while the feature/patch has been merged, the working document should serve as a source to -update the rest of the documentation. +Ideally, once the feature/patch has been merged, the working document should serve as a source to +update the rest of the documentation and then be removed. diff --git a/doc/book/src/working_documents/load_balancing.md b/doc/book/src/working_documents/load_balancing.md index f0f1a4d4..583b6086 100644 --- a/doc/book/src/working_documents/load_balancing.md +++ b/doc/book/src/working_documents/load_balancing.md @@ -1,4 +1,4 @@ -## Load Balancing Data +## Load Balancing Data (planned for version 0.2) I have conducted a quick study of different methods to load-balance data over different Garage nodes using consistent hashing.