doc/book/cookbook/real-world.md

@@ -19,10 +19,9 @@ To run a real-world deployment, make sure the following conditions are met:
 
 - You have at least three machines with sufficient storage space available.
 
-- Each machine has an IP address which makes it directly reachable by all other machines.
+- Each machine has a public IP address which is reachable by other machines. It
-  In many cases, nodes will be behind a NAT and will not each have a public
+  is highly recommended that you use IPv6 for this end-to-end connectivity. If
-  IPv4 addresses. In this case, is recommended that you use IPv6 for this
+  IPv6 is not available, then using a mesh VPN such as
-  end-to-end connectivity if it is available. Otherwise, using a mesh VPN such as
   [Nebula](https://github.com/slackhq/nebula) or
   [Yggdrasil](https://yggdrasil-network.github.io/) are approaches to consider
   in addition to building out your own VPN tunneling.
@@ -43,7 +42,7 @@ For our example, we will suppose the following infrastructure with IPv6 connecti
 | Brussels | Mars    | fc00:F::1  | 1.5 TB     |
 
 Note that Garage will **always** store the three copies of your data on nodes at different
-locations. This means that in the case of this small example, the usable capacity
+locations. This means that in the case of this small example, the available capacity
 of the cluster is in fact only 1.5 TB, because nodes in Brussels can't store more than that.
 This also means that nodes in Paris and London will be under-utilized.
 To make better use of the available hardware, you should ensure that the capacity
@@ -85,14 +84,14 @@ to store 2 TB of data in total.
 ## Get a Docker image
 
 Our docker image is currently named `dxflrs/garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated).
-We encourage you to use a fixed tag (eg. `v0.9.0`) and not the `latest` tag.
+We encourage you to use a fixed tag (eg. `v0.8.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.9.0` but it's up to you
+For this example, we will use the latest published version at the time of the writing which is `v0.8.0` but it's up to you
 to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated).
 
 For example:
 
 ```
-sudo docker pull dxflrs/garage:v0.9.0
+sudo docker pull dxflrs/garage:v0.8.0
 ```
 
 ## Deploying and configuring Garage
@@ -157,13 +156,12 @@ docker run \
   -v /etc/garage.toml:/etc/garage.toml \
   -v /var/lib/garage/meta:/var/lib/garage/meta \
   -v /var/lib/garage/data:/var/lib/garage/data \
-  dxflrs/garage:v0.9.0
+  dxflrs/garage:v0.8.0
 ```
 
-With this command line, Garage should be started automatically at each boot.
+It should be restarted automatically at each reboot.
-Please note that we use host networking as otherwise the network indirection
+Please note that we use host networking as otherwise Docker containers
-added by Docker would prevent Garage nodes from communicating with one another
+can not communicate with IPv6.
-(especially if using IPv6).
 
 If you want to use `docker-compose`, you may use the following `docker-compose.yml` file as a reference:
 
@@ -171,7 +169,7 @@ If you want to use `docker-compose`, you may use the following `docker-compose.y
 version: "3"
 services:
   garage:
-    image: dxflrs/garage:v0.9.0
+    image: dxflrs/garage:v0.8.0
     network_mode: "host"
     restart: unless-stopped
     volumes:
@@ -180,12 +178,10 @@ services:
       - /var/lib/garage/data:/var/lib/garage/data
 ```
 
-If you wish to upgrade your cluster, make sure to read the corresponding
+Upgrading between Garage versions should be supported transparently,
-[documentation page](@/documentation/operations/upgrading.md) first, as well as
+but please check the relase notes before doing so!
-the documentation relevant to your version of Garage in the case of major
+To upgrade, simply stop and remove this container and
-upgrades.  With the containerized setup proposed here, the upgrade process
+start again the command with a new version of Garage.
-will require stopping and removing the existing container, and re-creating it
-with the upgraded version.
 
 ## Controling the daemon
 
@@ -269,12 +265,12 @@ of a role that is assigned to each active cluster node.
 For our example, we will suppose we have the following infrastructure
 (Capacity, Identifier and Zone are specific values to Garage described in the following):
 
-| Location | Name    | Disk Space | Identifier | Zone (`-z`) | Capacity (`-c`) |
+| Location | Name    | Disk Space | `Capacity` | `Identifier` | `Zone` |
-|----------|---------|------------|------------|-------------|-----------------|
+|----------|---------|------------|------------|--------------|--------------|
-| Paris    | Mercury | 1 TB       | `563e`     | `par1`      | `1T`            |
+| Paris    | Mercury | 1 TB       | `10`       | `563e`     | `par1`       |
-| Paris    | Venus   | 2 TB       | `86f0`     | `par1`      | `2T`            |
+| Paris    | Venus   | 2 TB       | `20`       | `86f0`     | `par1`       |
-| London   | Earth   | 2 TB       | `6814`     | `lon1`      | `2T`            |
+| London   | Earth   | 2 TB       | `20`       | `6814`     | `lon1`       |
-| Brussels | Mars    | 1.5 TB     | `212f`     | `bru1`      | `1.5T`          |
+| Brussels | Mars    | 1.5 TB     | `15`       | `212f`     | `bru1`       |
 
 #### Node identifiers
 
@@ -296,8 +292,6 @@ garage status
 It will display the IP address associated with each node;
 from the IP address you will be able to recognize the node.
 
-We will now use the `garage layout assign` command to configure the correct parameters for each node.
-
 #### Zones
 
 Zones are simply a user-chosen identifier that identify a group of server that are grouped together logically.
@@ -307,29 +301,29 @@ In most cases, a zone will correspond to a geographical location (i.e. a datacen
 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.
 
-Zones are passed to Garage using the `-z` flag of `garage layout assign` (see below).
-
 #### Capacity
 
-Garage needs to know the storage capacity (disk space) it can/should use on
+Garage reasons on an abstract metric about disk storage that is named the *capacity* of a node.
-each node, to be able to correctly balance data.
+The capacity configured in Garage must be proportional to the disk space dedicated to the node.
 
-Capacity values are expressed in bytes and are passed to Garage using the `-c` flag of `garage layout assign` (see below).
+Capacity values must be **integers** but can be given any signification.
+Here we chose that 1 unit of capacity = 100 GB.
 
-#### Tags
+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,
-You can add additional tags to nodes using the `-t` flag of `garage layout assign` (see below).
+even if this means that capacities will not be strictly respected. For example in our above examples,
-Tags have no specific meaning for Garage and can be used at your convenience.
+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:
 
 ```bash
-garage layout assign 563e -z par1 -c 1T -t mercury
+garage layout assign 563e -z par1 -c 10 -t mercury
-garage layout assign 86f0 -z par1 -c 2T -t venus
+garage layout assign 86f0 -z par1 -c 20 -t venus
-garage layout assign 6814 -z lon1 -c 2T -t earth 
+garage layout assign 6814 -z lon1 -c 20 -t earth 
-garage layout assign 212f -z bru1 -c 1.5T -t mars 
+garage layout assign 212f -z bru1 -c 15 -t mars 
 ```
 
 At this point, the changes in the cluster layout have not yet been applied.
@@ -339,7 +333,6 @@ To show the new layout that will be applied, call:
 garage layout show
 ```
 
-Make sure to read carefully the output of `garage layout show`.
 Once you are satisfied with your new layout, apply it with:
 
 ```bash

doc/book/quick-start/_index.md

@@ -84,8 +84,9 @@ admin_token = "$(openssl rand -base64 32)"
 EOF
 ```
 
-Now that your configuration file has been created, you may save it to the directory of your choice.
+Now that your configuration file has been created, you can put
-By default, Garage looks for **`/etc/garage.toml`.**
+it in the right place. By default, garage looks at **`/etc/garage.toml`.**
+
 You can also store it somewhere else, but you will have to specify `-c path/to/garage.toml`
 at each invocation of the `garage` binary (for example: `garage -c ./garage.toml server`, `garage -c ./garage.toml status`).
 
@@ -102,14 +103,12 @@ your data to be persisted properly.
 
 ### Launching the Garage server
 
-Use the following command to launch the Garage server:
+Use the following command to launch the Garage server with our configuration file:
 
 ```
-garage -c path/to/garage.toml server
+garage server
 ```
 
-If you have placed the `garage.toml` file in `/etc` (its default location), you can simply run `garage server`.
-
 You can tune Garage's verbosity as follows (from less verbose to more verbose):
 
 ```
@@ -127,7 +126,7 @@ Log level `debug` can help you check why your S3 API calls are not working.
 The `garage` utility is also used as a CLI tool to configure your Garage deployment.
 It uses values from the TOML configuration file to find the Garage daemon running on the
 local node, therefore if your configuration file is not at `/etc/garage.toml` you will
-again have to specify `-c path/to/garage.toml` at each invocation.
+again have to specify `-c path/to/garage.toml`.
 
 If the `garage` CLI is able to correctly detect the parameters of your local Garage node,
 the following command should be enough to show the status of your cluster:
@@ -141,7 +140,7 @@ This should show something like this:
 ```
 ==== HEALTHY NODES ====
 ID                 Hostname  Address         Tag                   Zone  Capacity
-563e1ac825ee3323   linuxbox  127.0.0.1:3901  NO ROLE ASSIGNED
+563e1ac825ee3323…  linuxbox  127.0.0.1:3901  NO ROLE ASSIGNED
 ```
 
 ## Creating a cluster layout
@@ -154,12 +153,12 @@ For our test deployment, we are using only one node. The way in which we configu
 it does not matter, you can simply write:
 
 ```bash
-garage layout assign -z dc1 -c 1G <node_id>
+garage layout assign -z dc1 -c 1 <node_id>
 ```
 
 where `<node_id>` corresponds to the identifier of the node shown by `garage status` (first column).
 You can enter simply a prefix of that identifier.
-For instance here you could write just `garage layout assign -z dc1 -c 1G 563e`.
+For instance here you could write just `garage layout assign -z dc1 -c 1 563e`.
 
 The layout then has to be applied to the cluster, using:
 

doc/book/working-documents/migration-09.md

@@ -1,16 +1,13 @@
 +++
 title = "Migrating from 0.8 to 0.9"
-weight = 12
+weight = 14
 +++
 
 **This guide explains how to migrate to 0.9 if you have an existing 0.8 cluster.
 We don't recommend trying to migrate to 0.9 directly from 0.7 or older.**
 
-This migration procedure has been tested on several clusters without issues.
+**We make no guarantee that this migration will work perfectly:
-However, it is still a *critical procedure* that might cause issues.
+back up all your data before attempting it!**
-**Make sure to back up all your data before attempting it!**
-
-You might also want to read our [general documentation on upgrading Garage](@/documentation/operations/upgrading.md).
 
 The following are **breaking changes** in Garage v0.9 that require your attention when migrating: