From 0afc701a698c4891ea0f09fae668cb06b16757d7 Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Wed, 17 Mar 2021 14:44:14 +0100 Subject: [PATCH] Doc skeleton + intro --- doc/book/.gitignore | 1 + doc/book/book.toml | 6 ++ .../src/S3_Compatibility.md} | 0 doc/book/src/SUMMARY.md | 26 +++++++ doc/book/src/compatibility.md | 1 + doc/book/src/devenv.md | 17 +++++ doc/book/src/getting_started.md | 5 ++ doc/book/src/getting_started/bucket.md | 1 + doc/book/src/getting_started/cluster.md | 1 + doc/book/src/getting_started/files.md | 1 + doc/book/src/getting_started/install.md | 3 + doc/book/src/img/logo.svg | 44 ++++++++++++ doc/{Internals.md => book/src/internals.md} | 0 doc/book/src/intro.md | 62 ++++++++++++++++ doc/book/src/quickstart_bucket.md | 71 +++++++++++++++++++ .../src/related_work.md} | 0 doc/book/src/website.md | 1 + 17 files changed, 240 insertions(+) create mode 100644 doc/book/.gitignore create mode 100644 doc/book/book.toml rename doc/{Compatibility.md => book/src/S3_Compatibility.md} (100%) create mode 100644 doc/book/src/SUMMARY.md create mode 100644 doc/book/src/compatibility.md create mode 100644 doc/book/src/devenv.md create mode 100644 doc/book/src/getting_started.md create mode 100644 doc/book/src/getting_started/bucket.md create mode 100644 doc/book/src/getting_started/cluster.md create mode 100644 doc/book/src/getting_started/files.md create mode 100644 doc/book/src/getting_started/install.md create mode 100644 doc/book/src/img/logo.svg rename doc/{Internals.md => book/src/internals.md} (100%) create mode 100644 doc/book/src/intro.md create mode 100644 doc/book/src/quickstart_bucket.md rename doc/{Related Work.md => book/src/related_work.md} (100%) create mode 100644 doc/book/src/website.md diff --git a/doc/book/.gitignore b/doc/book/.gitignore new file mode 100644 index 000000000..7585238ef --- /dev/null +++ b/doc/book/.gitignore @@ -0,0 +1 @@ +book diff --git a/doc/book/book.toml b/doc/book/book.toml new file mode 100644 index 000000000..3e1639903 --- /dev/null +++ b/doc/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Quentin Dufour"] +language = "en" +multilingual = false +src = "src" +title = "Garage Documentation" diff --git a/doc/Compatibility.md b/doc/book/src/S3_Compatibility.md similarity index 100% rename from doc/Compatibility.md rename to doc/book/src/S3_Compatibility.md diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md new file mode 100644 index 000000000..3e4618a11 --- /dev/null +++ b/doc/book/src/SUMMARY.md @@ -0,0 +1,26 @@ +# Summary + +[The Garage Data Store](./intro.md) + +- [Getting Started](./getting_started.md) + - [Installation](./getting_started/install.md) + - [Configure a cluster](./getting_started/cluster.md) + - [Create buckets and keys](./getting_started/bucket.md) + - [Handle files](./getting_started/files.md) + +# Cookbooks + +- [Host a website](./website.md) + +# Reference Manual + +- [S3 API](./compatibility.md) + +# Design + +- [Related Work](./related_work.md) +- [Internals](./internals.md) + +# Development + +- [Setup your environment](./devenv.md) diff --git a/doc/book/src/compatibility.md b/doc/book/src/compatibility.md new file mode 100644 index 000000000..acf9968b8 --- /dev/null +++ b/doc/book/src/compatibility.md @@ -0,0 +1 @@ +# S3 API diff --git a/doc/book/src/devenv.md b/doc/book/src/devenv.md new file mode 100644 index 000000000..6cb7c5542 --- /dev/null +++ b/doc/book/src/devenv.md @@ -0,0 +1,17 @@ +# Setup your development environment + +We propose the following quickstart to setup a full dev. environment as quickly as possible: + + 1. Setup a rust/cargo environment. eg. `dnf install rust cargo` + 2. Install awscli v2 by following the guide [here](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html). + 3. Run `cargo build` to build the project + 4. Run `./script/dev-cluster.sh` to launch a test cluster (feel free to read the script) + 5. Run `./script/dev-configure.sh` to configure your test cluster with default values (same datacenter, 100 tokens) + 6. Run `./script/dev-bucket.sh` to create a bucket named `eprouvette` and an API key that will be stored in `/tmp/garage.s3` + 7. Run `source ./script/dev-env-aws.sh` to configure your CLI environment + 8. You can use `garage` to manage the cluster. Try `garage --help`. + 9. You can use the `awsgrg` alias to add, remove, and delete files. Try `awsgrg help`, `awsgrg cp /proc/cpuinfo s3://eprouvette/cpuinfo.txt`, or `awsgrg ls s3://eprouvette`. `awsgrg` is a wrapper on the `aws s3` command pre-configured with the previously generated API key (the one in `/tmp/garage.s3`) and localhost as the endpoint. + +Now you should be ready to start hacking on garage! + + diff --git a/doc/book/src/getting_started.md b/doc/book/src/getting_started.md new file mode 100644 index 000000000..7d3efd8b7 --- /dev/null +++ b/doc/book/src/getting_started.md @@ -0,0 +1,5 @@ +# Gettin Started + +Let's start your Garage journey! +In this chapter, we explain how to deploy a simple garage cluster and start interacting with it. +Our goal is to introduce you to Garage's workflows. diff --git a/doc/book/src/getting_started/bucket.md b/doc/book/src/getting_started/bucket.md new file mode 100644 index 000000000..c3b39d8d4 --- /dev/null +++ b/doc/book/src/getting_started/bucket.md @@ -0,0 +1 @@ +# Create buckets and keys diff --git a/doc/book/src/getting_started/cluster.md b/doc/book/src/getting_started/cluster.md new file mode 100644 index 000000000..868379b93 --- /dev/null +++ b/doc/book/src/getting_started/cluster.md @@ -0,0 +1 @@ +# Configure a cluster diff --git a/doc/book/src/getting_started/files.md b/doc/book/src/getting_started/files.md new file mode 100644 index 000000000..c8042dd36 --- /dev/null +++ b/doc/book/src/getting_started/files.md @@ -0,0 +1 @@ +# Handle files diff --git a/doc/book/src/getting_started/install.md b/doc/book/src/getting_started/install.md new file mode 100644 index 000000000..39557f029 --- /dev/null +++ b/doc/book/src/getting_started/install.md @@ -0,0 +1,3 @@ +# Installation + + diff --git a/doc/book/src/img/logo.svg b/doc/book/src/img/logo.svg new file mode 100644 index 000000000..fb02c40bb --- /dev/null +++ b/doc/book/src/img/logo.svg @@ -0,0 +1,44 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/Internals.md b/doc/book/src/internals.md similarity index 100% rename from doc/Internals.md rename to doc/book/src/internals.md diff --git a/doc/book/src/intro.md b/doc/book/src/intro.md new file mode 100644 index 000000000..5455ae714 --- /dev/null +++ b/doc/book/src/intro.md @@ -0,0 +1,62 @@ +![Garage's Logo](img/logo.svg) + +# The Garage Geo-Distributed Data Store + +Garage is a lightweight geo-distributed data store. +It comes from the observation that despite numerous object stores +many people have broken data management policies (backup/replication on a single site or none at all). +To promote better data management policies, with focused on the following desirable properties: + + - **Self-contained & lightweight**: works everywhere and integrates well in existing environments to target hyperconverged infrastructures + - **Highly resilient**: highly resilient to network failures, network latency, disk failures, sysadmin failures + - **Simple**: simple to understand, simple to operate, simple to debug + - **Internet enabled**: Made for multi-sites (eg. datacenter, offices, etc.) interconnected through a regular internet connection. + +We also noted that the pursuit of some other goals are detrimental to our initial goals. +The following have been identified has non-goals, if it matters to you, you should not use Garage: + + - **Extreme performances**: high performances constrain a lot the design and the deployment. We always prioritize + - **Feature extensiveness**: Complete implementation of the S3 API + - **Storage optimizations**: Erasure coding (our replication model is simply to copy the data as is on several nodes, in different datacenters if possible) + - **POSIX/Filesystem compatibility**: We do not aim at being POSIX compatible or to emulate any kind of filesystem. Indeed, in a distributed environment, such syncronizations are translated in network messages that impose severe constraints on the deployment. + +## Integration in environments + +Garage speaks (or will speak) the following protocols: + + - [S3](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html) - *SUPPORTED* - Enable applications to store large blobs such as pictures, video, images, documents, etc. S3 is versatile enough to also be used to publish a static website. + - [IMAP](https://github.com/go-pluto/pluto) - *PLANNED* - email storage is quite complex to get good oerformances. +To keep performances optimals, most imap servers only support on-disk storage. +We plan to add logic to Garage to make it a viable solution for email storage. + - *More to come* + +## Use Cases + +**[Deuxfleurs](https://deuxfleurs.fr) :** Garage is used by Deuxfleurs which is a non-profit hosting organization. +Especially, it is used to host their main website, this documentation and some of its members's blogs. Additionally, +Garage is used as a [backend for Nextcloud](https://docs.nextcloud.com/server/20/admin_manual/configuration_files/primary_storage.html). Deuxfleurs also plans to use Garage as their [Matrix's media backend](https://github.com/matrix-org/synapse-s3-storage-provider) and has the backend of [OCIS](https://github.com/owncloud/ocis). + +*Are you using Garage? Open a pull request to add your organization here!* + +## Comparisons to existing software + +**[Minio](https://min.io/) :** Minio shares our *self-contained & lightweight* goal but selected two of our non-goals: *storage optimizations* through erasure coding and *POSIX/Filesystem compatibility* through strong consistency. +However, by pursuing these two non-goals, minio do not reach our desirable properties. +First, it fails on the *simple* property: due to the erasure coding, minio has severe limitations on how drives can be added or deleted from a cluster. +Second, it fails on the *interned enabled* property: due to its strong consistency, minio is latency sensitive. +Furthermore, minio has no knowledge of "sites" and thus can not distribute data to minimize the failure of a given site. + +**[Openstack Swift](https://docs.openstack.org/swift/latest/)** +OpenStack Swift at least fails on the *self-contained & lightweight* goal. +Starting it requires around 8Gb of RAM, which is too much especially in an hyperconverged infrastructure. +It seems also to be far from *Simple*. + +**[Pithos](https://github.com/exoscale/pithos)** +Pithos has been abandonned and should probably not used yet, in the following we explain why we did not pick their design. +Pithos was relying as a S3 proxy in front of Cassandra (and was working with Scylla DB too). +From its designers' mouth, storing data in Cassandra has shown its limitations justifying the project abandonment. +They built a closed-source version 2 that does not store blobs in the database (only metadata) but did not communicate further on it. +We considered there v2's design but concluded that it does not fit both our *Self-contained & lightweight* and *Simple* properties. It makes the development, the deployment and the operations more complicated while reducing the flexibility. + +**[IPFS](https://ipfs.io/)** +*Not written yet* diff --git a/doc/book/src/quickstart_bucket.md b/doc/book/src/quickstart_bucket.md new file mode 100644 index 000000000..bd574e14e --- /dev/null +++ b/doc/book/src/quickstart_bucket.md @@ -0,0 +1,71 @@ +# Configuring a cluster + +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/Related Work.md b/doc/book/src/related_work.md similarity index 100% rename from doc/Related Work.md rename to doc/book/src/related_work.md diff --git a/doc/book/src/website.md b/doc/book/src/website.md new file mode 100644 index 000000000..2ea82a9a5 --- /dev/null +++ b/doc/book/src/website.md @@ -0,0 +1 @@ +# Host a website