devnode/garage-unix-socket
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

WIP doc

Browse source
This commit is contained in:
Quentin 2021-03-17 18:01:06 +01:00
parent 60f994a118
commit 468e45ed7f
2 changed files with 74 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
doc/book/src/getting_started/binary.md
View file

@ -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
```

64
doc/book/src/getting_started/daemon.md
View file

@ -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