Deuxfleurs/garage
48
56
Fork 73
Code Issues 100 Pull requests 13 Releases 30 Wiki Activity

reorganize documentation for new website #213

Merged
lx merged 7 commits from doc-new-website into main 2022-02-07 10:51:12 +00:00
Conversation 0 Commits 7 Files changed 55 +40 -25
4 changed files with 40 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit 3885a5ea47 - Show all commits

22
doc/book/cookbook/exposing-websites.md
View file

@ -3,7 +3,19 @@ title = "Exposing buckets as websites"
weight = 25 weight = 25
+++ +++
You can expose your bucket as a website with this simple command: ## Configuring a bucket for website access
There are two methods to expose buckets as website:
1. using the PutBucketWebsite S3 API call, which is allowed for access keys that have the owner permission bit set
2. from the Garage CLI, by an adminstrator of the cluster
The `PutBucketWebsite` API endpoint [is documented](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketWebsite.html) in the official AWS docs.
This endpoint can also be called [using `aws s3api`](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-website.html) on the command line.
The website configuration supported by Garage is only a subset of the possibilities on Amazon S3: redirections are not supported, only the index document and error document can be specified.
If you want to expose your bucket as a website from the CLI, use this simple command:
```bash ```bash
garage bucket website --allow my-website garage bucket website --allow my-website
@ -11,10 +23,16 @@ garage bucket website --allow my-website
Now it will be **publicly** exposed on the web endpoint (by default listening on port 3902). Now it will be **publicly** exposed on the web endpoint (by default listening on port 3902).
## How exposed websites work
Our website serving logic is as follow: Our website serving logic is as follow:
- Supports only static websites (no support for PHP or other languages) - Supports only static websites (no support for PHP or other languages)
- Does not support directory listing - Does not support directory listing
- The index is defined in your `garage.toml`. ([ref](@/documentation/reference-manual/configuration.md#index)) - The index file is defined per-bucket and can be specified in the `PutBucketWebsite` call
or on the CLI using the `--index-document` parameter (default: `index.html`)
- A custom error document for 404 errors can be specified in the `PutBucketWebsite` call
or on the CLI using the `--error-document` parameter
Now we need to infer the URL of your website through your bucket name. Now we need to infer the URL of your website through your bucket name.
Let assume: Let assume:

3
doc/book/cookbook/gateways.md
View file

@ -15,9 +15,6 @@ You can configure Garage as a gateway on all nodes that will consume your S3 API
- **It simplifies security.** Instead of having to maintain and renew a TLS certificate, you leverage the Secret Handshake protocol we use for our cluster. The S3 API protocol will be in plain text but limited to your local machine. - **It simplifies security.** Instead of having to maintain and renew a TLS certificate, you leverage the Secret Handshake protocol we use for our cluster. The S3 API protocol will be in plain text but limited to your local machine.
## Limitations
Currently it will not work with minio client. Follow issue [#64](https://git.deuxfleurs.fr/Deuxfleurs/garage/issues/64) for more information.
## Spawn a Gateway ## Spawn a Gateway

2
doc/book/cookbook/recovering.md
View file

@ -94,7 +94,7 @@ might be faster but most of the pieces will be deleted anyway from the disk and
First, set up a new drive to store the metadata directory for the replacement node (a SSD is recommended), First, set up a new drive to store the metadata directory for the replacement node (a SSD is recommended),
and for the data directory if necessary. You can then start Garage on the new node. and for the data directory if necessary. You can then start Garage on the new node.
The restarted node should generate a new node ID, and it should be shown as `NOT CONFIGURED` in `garage status`. The restarted node should generate a new node ID, and it should be shown with `NO ROLE ASSIGNED` in `garage status`.
The ID of the lost node should be shown in `garage status` in the section for disconnected/unavailable nodes. The ID of the lost node should be shown in `garage status` in the section for disconnected/unavailable nodes.
Then, replace the broken node by the new one, using: Then, replace the broken node by the new one, using:

38
doc/book/reference-manual/configuration.md
View file

@ -47,7 +47,7 @@ The following gives details about each available configuration option.
## Available configuration options ## Available configuration options
#### `metadata_dir` ### `metadata_dir`
The directory in which Garage will store its metadata. This contains the node identifier, The directory in which Garage will store its metadata. This contains the node identifier,
the network configuration and the peer list, the list of buckets and keys as well the network configuration and the peer list, the list of buckets and keys as well
@ -55,14 +55,14 @@ as the index of all objects, object version and object blocks.
Store this folder on a fast SSD drive if possible to maximize Garage's performance. Store this folder on a fast SSD drive if possible to maximize Garage's performance.
#### `data_dir` ### `data_dir`
The directory in which Garage will store the data blocks of objects. The directory in which Garage will store the data blocks of objects.
This folder can be placed on an HDD. The space available for `data_dir` This folder can be placed on an HDD. The space available for `data_dir`
should be counted to determine a node's capacity should be counted to determine a node's capacity
when [configuring it](@/documentation/cookbook/real-world.md). when [configuring it](@/documentation/cookbook/real-world.md).
#### `block_size` ### `block_size`
Garage splits stored objects in consecutive chunks of size `block_size` Garage splits stored objects in consecutive chunks of size `block_size`
(except the last one which might be smaller). The default size is 1MB and (except the last one which might be smaller). The default size is 1MB and
@ -74,7 +74,7 @@ means that chunks from existing files will not be deduplicated with chunks
from newly uploaded files, meaning you might use more storage space that is from newly uploaded files, meaning you might use more storage space that is
optimally possible. optimally possible.
#### `replication_mode` ### `replication_mode`
Garage supports the following replication modes: Garage supports the following replication modes:
@ -127,7 +127,7 @@ Compression is done synchronously, setting a value too high will add latency to
This value can be different between nodes, compression is done by the node which receive the This value can be different between nodes, compression is done by the node which receive the
API call. API call.
#### `rpc_secret` ### `rpc_secret`
Garage uses a secret key that is shared between all nodes of the cluster Garage uses a secret key that is shared between all nodes of the cluster
in order to identify these nodes and allow them to communicate together. in order to identify these nodes and allow them to communicate together.
@ -135,7 +135,7 @@ This key should be specified here in the form of a 32-byte hex-encoded
random string. Such a string can be generated with a command random string. Such a string can be generated with a command
such as `openssl rand -hex 32`. such as `openssl rand -hex 32`.
#### `rpc_bind_addr` ### `rpc_bind_addr`
The address and port on which to bind for inter-cluster communcations The address and port on which to bind for inter-cluster communcations
(reffered to as RPC for remote procedure calls). (reffered to as RPC for remote procedure calls).
@ -144,14 +144,14 @@ the node, even in the case of a NAT: the NAT should be configured to forward the
port number to the same internal port nubmer. This means that if you have several nodes running port number to the same internal port nubmer. This means that if you have several nodes running
behind a NAT, they should each use a different RPC port number. behind a NAT, they should each use a different RPC port number.
#### `rpc_public_addr` ### `rpc_public_addr`
The address and port that other nodes need to use to contact this node for The address and port that other nodes need to use to contact this node for
RPC calls. **This parameter is optional but recommended.** In case you have RPC calls. **This parameter is optional but recommended.** In case you have
a NAT that binds the RPC port to a port that is different on your public IP, a NAT that binds the RPC port to a port that is different on your public IP,
this field might help making it work. this field might help making it work.
#### `bootstrap_peers` ### `bootstrap_peers`
A list of peer identifiers on which to contact other Garage peers of this cluster. A list of peer identifiers on which to contact other Garage peers of this cluster.
These peer identifiers have the following syntax: These peer identifiers have the following syntax:
@ -167,7 +167,7 @@ be obtained by running `garage node id` and then included directly in the
key will be returned by `garage node id` and you will have to add the IP key will be returned by `garage node id` and you will have to add the IP
yourself. yourself.
#### `consul_host` and `consul_service_name` ### `consul_host` and `consul_service_name`
Garage supports discovering other nodes of the cluster using Consul. Garage supports discovering other nodes of the cluster using Consul.
This works only when nodes are announced in Consul by an orchestrator such as Nomad, This works only when nodes are announced in Consul by an orchestrator such as Nomad,
@ -177,7 +177,7 @@ The `consul_host` parameter should be set to the hostname of the Consul server,
and `consul_service_name` should be set to the service name under which Garage's and `consul_service_name` should be set to the service name under which Garage's
RPC ports are announced. RPC ports are announced.
#### `sled_cache_capacity` ### `sled_cache_capacity`
This parameter can be used to tune the capacity of the cache used by This parameter can be used to tune the capacity of the cache used by
[sled](https://sled.rs), the database Garage uses internally to store metadata. [sled](https://sled.rs), the database Garage uses internally to store metadata.
@ -185,7 +185,7 @@ Tune this to fit the RAM you wish to make available to your Garage instance.
More cache means faster Garage, but the default value (128MB) should be plenty More cache means faster Garage, but the default value (128MB) should be plenty
for most use cases. for most use cases.
#### `sled_flush_every_ms` ### `sled_flush_every_ms`
This parameters can be used to tune the flushing interval of sled. This parameters can be used to tune the flushing interval of sled.
Increase this if sled is thrashing your SSD, at the risk of losing more data in case Increase this if sled is thrashing your SSD, at the risk of losing more data in case
@ -193,20 +193,21 @@ of a power outage (though this should not matter much as data is replicated on o
nodes). The default value, 2000ms, should be appropriate for most use cases. nodes). The default value, 2000ms, should be appropriate for most use cases.
## The `[s3_api]` section ## The `[s3_api]` section
#### `api_bind_addr` ### `api_bind_addr`
The IP and port on which to bind for accepting S3 API calls. The IP and port on which to bind for accepting S3 API calls.
This endpoint does not suport TLS: a reverse proxy should be used to provide it. This endpoint does not suport TLS: a reverse proxy should be used to provide it.
#### `s3_region` ### `s3_region`
Garage will accept S3 API calls that are targetted to the S3 region defined here. Garage will accept S3 API calls that are targetted to the S3 region defined here.
API calls targetted to other regions will fail with a AuthorizationHeaderMalformed error API calls targetted to other regions will fail with a AuthorizationHeaderMalformed error
message that redirects the client to the correct region. message that redirects the client to the correct region.
#### `root_domain` {#root_domain} ### `root_domain` {#root_domain}
The optionnal suffix to access bucket using vhost-style in addition to path-style request. The optionnal suffix to access bucket using vhost-style in addition to path-style request.
Note path-style requests are always enabled, whether or not vhost-style is configured. Note path-style requests are always enabled, whether or not vhost-style is configured.
@ -216,18 +217,20 @@ but might be required by softwares not supporting path-style requests.
If `root_domain` is `s3.garage.eu`, a bucket called `my-bucket` can be interacted with If `root_domain` is `s3.garage.eu`, a bucket called `my-bucket` can be interacted with
using the hostname `my-bucket.s3.garage.eu`. using the hostname `my-bucket.s3.garage.eu`.
## The `[s3_web]` section ## The `[s3_web]` section
Garage allows to publish content of buckets as websites. This section configures the Garage allows to publish content of buckets as websites. This section configures the
behaviour of this module. behaviour of this module.
#### `bind_addr` ### `bind_addr`
The IP and port on which to bind for accepting HTTP requests to buckets configured The IP and port on which to bind for accepting HTTP requests to buckets configured
for website access. for website access.
This endpoint does not suport TLS: a reverse proxy should be used to provide it. This endpoint does not suport TLS: a reverse proxy should be used to provide it.
#### `root_domain` ### `root_domain`
The optionnal suffix appended to bucket names for the corresponding HTTP Host. The optionnal suffix appended to bucket names for the corresponding HTTP Host.
@ -235,6 +238,3 @@ For instance, if `root_domain` is `web.garage.eu`, a bucket called `deuxfleurs.f
will be accessible either with hostname `deuxfleurs.fr.web.garage.eu` will be accessible either with hostname `deuxfleurs.fr.web.garage.eu`
or with hostname `deuxfleurs.fr`. or with hostname `deuxfleurs.fr`.
#### `index`
The name of the index file to return for requests ending with `/` (usually `index.html`).