Working on the getting started guide

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)

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".

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.

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.

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:
 
-
+```
-
+sudo docker pull lxpz/garage_amd64:v0.1.1d
-### Multiple machine deployment with docker
+```
 
 ## From source
+
+

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"
+```
+
+

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.

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 
+Ideally, once the feature/patch has been merged, the working document should serve as a source to 
-update the rest of the documentation.
+update the rest of the documentation and then be removed.

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.