aboutsummaryrefslogtreecommitdiff
path: root/doc/book/src
diff options
context:
space:
mode:
authorQuentin Dufour <quentin@deuxfleurs.fr>2021-03-17 18:01:06 +0100
committerQuentin Dufour <quentin@deuxfleurs.fr>2021-03-17 18:01:06 +0100
commit468e45ed7f47ce41f196274519c6b59f3bf46f0e (patch)
tree5b77d64c8dbffc7e7050db921a2a685321856ea9 /doc/book/src
parent60f994a118afdde241d9a2296e2e8e090e08674d (diff)
downloadgarage-468e45ed7f47ce41f196274519c6b59f3bf46f0e.tar.gz
garage-468e45ed7f47ce41f196274519c6b59f3bf46f0e.zip
WIP doc
Diffstat (limited to 'doc/book/src')
-rw-r--r--doc/book/src/getting_started/binary.md22
-rw-r--r--doc/book/src/getting_started/daemon.md64
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