diff options
| -rw-r--r-- | content/documentation/connect/_index.md | 46 | ||||
| -rw-r--r-- | content/documentation/cookbook/_index.md | 30 | ||||
| -rw-r--r-- | content/documentation/design/_index.md | 30 | ||||
| -rw-r--r-- | content/documentation/development/_index.md | 18 | ||||
| -rw-r--r-- | content/documentation/quick_start.md | 1 | ||||
| -rw-r--r-- | content/documentation/reference-manual/_index.md | 9 | ||||
| -rw-r--r-- | content/documentation/working-documents/_index.md | 12 | ||||
| -rw-r--r-- | templates/documentation.html | 11 | ||||
| -rw-r--r-- | templates/partials/doc/global_toc.html | 11 |
9 files changed, 148 insertions, 20 deletions
diff --git a/content/documentation/connect/_index.md b/content/documentation/connect/_index.md index ff3976a..8ae3e60 100644 --- a/content/documentation/connect/_index.md +++ b/content/documentation/connect/_index.md @@ -2,5 +2,47 @@ title = "Integrations" weight = 3 sort_by = "weight" -redirect_to = "documentation/connect/apps/" -+++
\ No newline at end of file +template = "documentation.html" ++++ + + + +Garage implements the Amazon S3 protocol, which makes it compatible with many existing software programs. + +In particular, you will find here instructions to connect it with: + + - [web applications](./apps.md) + - [website hosting](./websites.md) + - [software repositories](./repositories.md) + - [CLI tools](./cli.md) + - [your own code](./code.md) + +### Generic instructions + +To configure S3-compatible software to interact with Garage, +you will need the following parameters: + +- An **API endpoint**: this corresponds to the HTTP or HTTPS address + used to contact the Garage server. When runing Garage locally this will usually + be `http://127.0.0.1:3900`. In a real-world setting, you would usually have a reverse-proxy + that adds TLS support and makes your Garage server available under a public hostname + such as `https://garage.example.com`. + +- An **API access key** and its associated **secret key**. These usually look something + like this: `GK3515373e4c851ebaad366558` (access key), + `7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34` (secret key). + These keys are created and managed using the `garage` CLI, as explained in the + [quick start](../quick_start/index.md) guide. + +Most S3 clients can be configured easily with these parameters, +provided that you follow the following guidelines: + +- **Force path style:** Garage does not support DNS-style buckets, which are now by default + on Amazon S3. Instead, Garage uses the legacy path-style bucket addressing. + Remember to configure your client to acknowledge this fact. + +- **Configuring the S3 region:** Garage requires your client to talk to the correct "S3 region", + which is set in the configuration file. This is often set just to `garage`. + If this is not configured explicitly, clients usually try to talk to region `us-east-1`. + Garage should normally redirect your client to the correct region, + but in case your client does not support this you might have to configure it manually. diff --git a/content/documentation/cookbook/_index.md b/content/documentation/cookbook/_index.md index c788f18..4216f02 100644 --- a/content/documentation/cookbook/_index.md +++ b/content/documentation/cookbook/_index.md @@ -1,6 +1,32 @@ +++ title="Cookbook" +template = "documentation.html" weight = 2 sort_by = "weight" -redirect_to = "documentation/cookbook/real-world/" -+++
\ No newline at end of file ++++ + + +A cookbook, when you cook, is a collection of recipes. +Similarly, Garage's cookbook contains a collection of recipes that are known to works well! +This chapter could also be referred as "Tutorials" or "Best practices". + +- **[Multi-node deployment](real_world.md):** This page will walk you through all of the necessary + steps to deploy Garage in a real-world setting. + +- **[Building from source](from_source.md):** This page explains how to build Garage from + source in case a binary is not provided for your architecture, or if you want to + hack with us! + +- **[Integration with Systemd](systemd.md):** This page explains how to run Garage + as a Systemd service (instead of as a Docker container). + +- **[Configuring a gateway node](gateways.md):** This page explains how to run a gateway node in a Garage cluster, i.e. a Garage node that doesn't store data but accelerates access to data present on the other nodes. + +- **[Hosting a website](exposing_websites.md):** This page explains how to use Garage + to host a static website. + +- **[Configuring a reverse-proxy](reverse_proxy.md):** This page explains how to configure a reverse-proxy to add TLS support to your S3 api endpoint. + +- **[Recovering from failures](recovering.md):** Garage's first selling point is resilience + to hardware failures. This section explains how to recover from such a failure in the + best possible way. diff --git a/content/documentation/design/_index.md b/content/documentation/design/_index.md index 1b4c7f7..362853b 100644 --- a/content/documentation/design/_index.md +++ b/content/documentation/design/_index.md @@ -2,5 +2,31 @@ title = "Design" weight = 5 sort_by = "weight" -redirect_to = "documentation/design/goals/" -+++
\ No newline at end of file +template = "documentation.html" ++++ + + +The design section helps you to see Garage from a "big picture" +perspective. It will allow you to understand if Garage is a good fit for +you, how to better use it, how to contribute to it, what can Garage could +and could not do, etc. + +- **[Goals and use cases](goals.md):** This page explains why Garage was concieved and what practical use cases it targets. + +- **[Related work](related_work.md):** This pages presents the theoretical background on which Garage is built, and describes other software storage solutions and why they didn't work for us. + +- **[Internals](internals.md):** This page enters into more details on how Garage manages data internally. + +## Talks + +We love to talk and hear about Garage, that's why we keep a log here: + + - [(fr, 2021-11-13, video) Garage : Mille et une façons de stocker vos données](https://video.tedomum.net/w/moYKcv198dyMrT8hCS5jz9) and [slides (html)](https://rfid.deuxfleurs.fr/presentations/2021-11-13/garage/) - during [RFID#1](https://rfid.deuxfleurs.fr/programme/2021-11-13/) event + + - [(en, 2021-04-28) Distributed object storage is centralised](https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/commit/b1f60579a13d3c5eba7f74b1775c84639ea9b51a/doc/talks/2021-04-28_spirals-team/talk.pdf) + + - [(fr, 2020-12-02) Garage : jouer dans la cour des grands quand on est un hébergeur associatif](https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/commit/b1f60579a13d3c5eba7f74b1775c84639ea9b51a/doc/talks/2020-12-02_wide-team/talk.pdf) + +*Did you write or talk about Garage? [Open a pull request](https://git.deuxfleurs.fr/Deuxfleurs/garage/) to add a link here!* + + diff --git a/content/documentation/development/_index.md b/content/documentation/development/_index.md index 56994af..5f0c152 100644 --- a/content/documentation/development/_index.md +++ b/content/documentation/development/_index.md @@ -2,5 +2,19 @@ title = "Development" weight = 6 sort_by = "weight" -redirect_to = "documentation/development/devenv/" -+++
\ No newline at end of file +template = "documentation.html" ++++ + + +Now that you are a Garage expert, you want to enhance it, you are in the right place! +We discuss here how to hack on Garage, how we manage its development, etc. + +## Rust API (docs.rs) +If you encounter a specific bug in Garage or plan to patch it, you may jump directly to the source code's documentation! + + - [garage\_api](https://docs.rs/garage_api/latest/garage_api/) - contains the S3 standard API endpoint + - [garage\_model](https://docs.rs/garage_model/latest/garage_model/) - contains Garage's model built on the table abstraction + - [garage\_rpc](https://docs.rs/garage_rpc/latest/garage_rpc/) - contains Garage's federation protocol + - [garage\_table](https://docs.rs/garage_table/latest/garage_table/) - contains core Garage's CRDT datatypes + - [garage\_util](https://docs.rs/garage_util/latest/garage_util/) - contains garage helpers + - [garage\_web](https://docs.rs/garage_web/latest/garage_web/) - contains the S3 website endpoint diff --git a/content/documentation/quick_start.md b/content/documentation/quick_start.md index 30cf2ee..617d1d5 100644 --- a/content/documentation/quick_start.md +++ b/content/documentation/quick_start.md @@ -3,7 +3,6 @@ title = "Quick Start" weight = 5 +++ -# Quick Start Let's start your Garage journey! In this chapter, we explain how to deploy Garage as a single-node server diff --git a/content/documentation/reference-manual/_index.md b/content/documentation/reference-manual/_index.md index ee79581..2718f4e 100644 --- a/content/documentation/reference-manual/_index.md +++ b/content/documentation/reference-manual/_index.md @@ -2,5 +2,10 @@ title = "Reference Manual" weight = 4 sort_by = "weight" -redirect_to = "documentation/reference-manual/configuration/" -+++
\ No newline at end of file +template = "documentation.html" ++++ + + +A reference manual contains some extensive descriptions about the features and the behaviour of the software. +Reading of this chapter is recommended once you have a good knowledge/understanding of Garage. +It will be useful if you want to tune it or to use it in some exotic conditions. diff --git a/content/documentation/working-documents/_index.md b/content/documentation/working-documents/_index.md index 8b65867..cb78fc4 100644 --- a/content/documentation/working-documents/_index.md +++ b/content/documentation/working-documents/_index.md @@ -2,5 +2,13 @@ title = "Working Documents" weight = 7 sort_by = "weight" -redirect_to = "documentation/working-documents/compatibility-target/" -+++
\ No newline at end of file +template = "documentation.html" ++++ + + +Working documents are documents that reflect the fact that Garage is a software that evolves quickly. +They are a way to communicate our ideas, our changes, and so on before or while we are implementing them in Garage. +If you like to live on the edge, it could also serve as a documentation of our next features to be released. + +Ideally, once the feature/patch has been merged, the working document should serve as a source to +update the rest of the documentation and then be removed. diff --git a/templates/documentation.html b/templates/documentation.html index 55a5c61..154df5f 100644 --- a/templates/documentation.html +++ b/templates/documentation.html @@ -1,11 +1,13 @@ {% extends 'base.html' %} {% block title %} - {{ config.title }} | {{ page.title }} + {{ config.title }} | {% if page %}{{ page.title }}{% else %}{{ section.title }}{% endif %} {% endblock %} {% block content %} - {% set section = get_section(path="documentation/_index.md") %} + {% if not page %} + {% set page = section %} + {% endif %} <section id="documentation-section" class="section overflow-x-hidden"> <div class="grid grid-cols-1 xl:grid-cols-5"> {% include "partials/doc/global_toc.html" %} @@ -45,7 +47,10 @@ {% endblock %} {% block custom_js %} + {% if not page %} + {% set page = section %} + {% endif %} {% if page.toc %} {% include "partials/doc/toc_script.html" %} {% endif %} -{% endblock %}
\ No newline at end of file +{% endblock %} diff --git a/templates/partials/doc/global_toc.html b/templates/partials/doc/global_toc.html index f739f49..277739c 100644 --- a/templates/partials/doc/global_toc.html +++ b/templates/partials/doc/global_toc.html @@ -1,3 +1,4 @@ + {% set section = get_section(path="documentation/_index.md") %} <aside id="global_toc" class="relative col-span-1 h-full bg-gray-100 shadow-inner border-r border-t border-gray-200"> {% if section.subsections %} <ul id="main-toc-menu" class="space-y-2 px-6 py-3 list-none"> @@ -6,8 +7,8 @@ {% for page in section.pages %} <a href="{{ page.permalink | safe }}" - class="docPage block pl-2 py-1 border-l rounded-r border-garage-orange hover:bg-garage-orange hover:bg-opacity-20 - {% if current_path == page.path %} activePage border-l-4 text-garage-orange font-semibold border-opacity-100 border-garage-orange {% endif %}"> + class="bg-white border border-garage-orange block p-1 rounded block font-semibold hover:bg-garage-orange hover:bg-opacity-20 + {% if current_path == page.path %} activePage text-garage-orange border-opacity-100 border-garage-orange {% endif %}"> {{ page.title }} </a> {% endfor %} @@ -18,7 +19,9 @@ <li class="relative"> <a href="{{ h1.permalink | safe }}" - class="bg-white border border-garage-orange block p-1 rounded-r rounded-tl font-semibold text-gray-800"> + class="bg-white border border-garage-orange block p-1 rounded-r rounded-tl font-semibold + {% if current_path == h1.path %} activePage text-garage-orange font-semibold border-opacity-100 border-garage-orange {% else %}text-gray-800{% endif %} + "> {{ h1.title }} </a> {% if h1.pages %} @@ -43,4 +46,4 @@ {% endfor %} </ul> {% endif %} -</aside>
\ No newline at end of file +</aside> |