aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlex Auvolat <alex@adnab.me>2022-01-31 12:44:47 +0100
committerAlex Auvolat <alex@adnab.me>2022-01-31 12:44:47 +0100
commit242fcc297903c2e47c35946da5f99f97d091de0a (patch)
tree97ae176f98015a2006986ba9d69cc930bab6286f
parent143c9403e6c94585de1ab65e631798994d01eb41 (diff)
downloadgaragehq.deuxfleurs.fr-242fcc297903c2e47c35946da5f99f97d091de0a.tar.gz
garagehq.deuxfleurs.fr-242fcc297903c2e47c35946da5f99f97d091de0a.zip
Add sections as documentation pages
-rw-r--r--content/documentation/connect/_index.md46
-rw-r--r--content/documentation/cookbook/_index.md30
-rw-r--r--content/documentation/design/_index.md30
-rw-r--r--content/documentation/development/_index.md18
-rw-r--r--content/documentation/quick_start.md1
-rw-r--r--content/documentation/reference-manual/_index.md9
-rw-r--r--content/documentation/working-documents/_index.md12
-rw-r--r--templates/documentation.html11
-rw-r--r--templates/partials/doc/global_toc.html11
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>