Add sections as documentation pages

This commit is contained in:
Alex 2022-01-31 12:44:47 +01:00
parent 143c9403e6
commit 242fcc2979
No known key found for this signature in database
GPG key ID: EDABF9711E244EB1
9 changed files with 148 additions and 20 deletions

View file

@ -2,5 +2,47 @@
title = "Integrations"
weight = 3
sort_by = "weight"
redirect_to = "documentation/connect/apps/"
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.

View file

@ -1,6 +1,32 @@
+++
title="Cookbook"
template = "documentation.html"
weight = 2
sort_by = "weight"
redirect_to = "documentation/cookbook/real-world/"
+++
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.

View file

@ -2,5 +2,31 @@
title = "Design"
weight = 5
sort_by = "weight"
redirect_to = "documentation/design/goals/"
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!*

View file

@ -2,5 +2,19 @@
title = "Development"
weight = 6
sort_by = "weight"
redirect_to = "documentation/development/devenv/"
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

View file

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

View file

@ -2,5 +2,10 @@
title = "Reference Manual"
weight = 4
sort_by = "weight"
redirect_to = "documentation/reference-manual/configuration/"
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.

View file

@ -2,5 +2,13 @@
title = "Working Documents"
weight = 7
sort_by = "weight"
redirect_to = "documentation/working-documents/compatibility-target/"
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.

View file

@ -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,6 +47,9 @@
{% endblock %}
{% block custom_js %}
{% if not page %}
{% set page = section %}
{% endif %}
{% if page.toc %}
{% include "partials/doc/toc_script.html" %}
{% endif %}

View file

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