diff options
Diffstat (limited to 'doc/book/src/getting_started')
-rw-r--r-- | doc/book/src/getting_started/bucket.md | 70 | ||||
-rw-r--r-- | doc/book/src/getting_started/install.md | 22 |
2 files changed, 92 insertions, 0 deletions
diff --git a/doc/book/src/getting_started/bucket.md b/doc/book/src/getting_started/bucket.md index c3b39d8d..8b05ee23 100644 --- a/doc/book/src/getting_started/bucket.md +++ b/doc/book/src/getting_started/bucket.md @@ -1 +1,71 @@ # Create buckets and keys + +First, chances are that your garage deployment is secured by TLS. +All your commands must be prefixed with their certificates. +I will define an alias once and for all to ease future commands. +Please adapt the path of the binary and certificates to your installation! + +``` +alias grg="/garage/garage --ca-cert /secrets/garage-ca.crt --client-cert /secrets/garage.crt --client-key /secrets/garage.key" +``` + +Now we can check that everything is going well by checking our cluster status: + +``` +grg status +``` + +Don't forget that `help` command and `--help` subcommands can help you anywhere, the CLI tool is self-documented! Two examples: + +``` +grg help +grg bucket allow --help +``` + +Fine, now let's create a bucket (we imagine that you want to deploy nextcloud): + +``` +grg bucket create nextcloud-bucket +``` + +Check that everything went well: + +``` +grg bucket list +grg bucket info nextcloud-bucket +``` + +Now we will generate an API key to access this bucket. +Note that API keys are independent of buckets: one key can access multiple buckets, multiple keys can access one bucket. + +Now, let's start by creating a key only for our PHP application: + +``` +grg key new --name nextcloud-app-key +``` + +You will have the following output (this one is fake, `key_id` and `secret_key` were generated with the openssl CLI tool): + +``` +Key { key_id: "GK3515373e4c851ebaad366558", secret_key: "7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34", name: "nextcloud-app-key", name_timestamp: 1603280506694, deleted: false, authorized_buckets: [] } +``` + +Check that everything works as intended (be careful, info works only with your key identifier and not with its friendly name!): + +``` +grg key list +grg key info GK3515373e4c851ebaad366558 +``` + +Now that we have a bucket and a key, we need to give permissions to the key on the bucket! + +``` +grg bucket allow --read --write nextcloud-bucket --key GK3515373e4c851ebaad366558 +``` + +You can check at any times allowed keys on your bucket with: + +``` +grg bucket info nextcloud-bucket +``` + diff --git a/doc/book/src/getting_started/install.md b/doc/book/src/getting_started/install.md index 39557f02..98af1283 100644 --- a/doc/book/src/getting_started/install.md +++ b/doc/book/src/getting_started/install.md @@ -1,3 +1,25 @@ # Installation +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). +We did not test other architecture/operating system but, as long as your architecture/operating system is supported by Rust, you should be able to run Garage (feel free to report your tests!). +## 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 + + + +### Multiple machine deployment with docker + +## From source |