aboutsummaryrefslogtreecommitdiff
path: root/doc/book/src/cookbook/reverse_proxy.md
diff options
context:
space:
mode:
authorAlex <alex@adnab.me>2022-02-07 11:51:12 +0100
committerAlex <alex@adnab.me>2022-02-07 11:51:12 +0100
commit1c0ba930b8d6aa5d97e6942852240861e6ab9bed (patch)
treecddc9af5fc2378c76fe5ef6306f807e27648b7a7 /doc/book/src/cookbook/reverse_proxy.md
parent45d6d377d2011d8fb4ceb13bb4584df97c458525 (diff)
downloadgarage-1c0ba930b8d6aa5d97e6942852240861e6ab9bed.tar.gz
garage-1c0ba930b8d6aa5d97e6942852240861e6ab9bed.zip
Reorganize documentation for new website (#213)
This PR should be merged after the new website is deployed. - [x] Rename files - [x] Add front matter section to all `.md` files in the book (necessary for Zola) - [x] Change all internal links to use Zola's linking system that checks broken links - [x] Some updates to documentation contents and organization Co-authored-by: Alex Auvolat <alex@adnab.me> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/213 Co-authored-by: Alex <alex@adnab.me> Co-committed-by: Alex <alex@adnab.me>
Diffstat (limited to 'doc/book/src/cookbook/reverse_proxy.md')
-rw-r--r--doc/book/src/cookbook/reverse_proxy.md165
1 files changed, 0 insertions, 165 deletions
diff --git a/doc/book/src/cookbook/reverse_proxy.md b/doc/book/src/cookbook/reverse_proxy.md
deleted file mode 100644
index 14633ae8..00000000
--- a/doc/book/src/cookbook/reverse_proxy.md
+++ /dev/null
@@ -1,165 +0,0 @@
-# Configuring a reverse proxy
-
-The main reason to add a reverse proxy in front of Garage is to provide TLS to your users.
-
-In production you will likely need your certificates signed by a certificate authority.
-The most automated way is to use a provider supporting the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555)
-such as [Let's Encrypt](https://letsencrypt.org/), [ZeroSSL](https://zerossl.com/) or [Buypass Go SSL](https://www.buypass.com/ssl/products/acme).
-
-If you are only testing Garage, you can generate a self-signed certificate to follow the documentation:
-
-```bash
-openssl req \
- -new \
- -x509 \
- -keyout /tmp/garage.key \
- -out /tmp/garage.crt \
- -nodes \
- -subj "/C=XX/ST=XX/L=XX/O=XX/OU=XX/CN=localhost/emailAddress=X@X.XX" \
- -addext "subjectAltName = DNS:localhost, IP:127.0.0.1"
-
-cat /tmp/garage.key /tmp/garage.crt > /tmp/garage.pem
-```
-
-Be careful as you will need to allow self signed certificates in your client.
-For example, with minio, you must add the `--insecure` flag.
-An example:
-
-```bash
-mc ls --insecure garage/
-```
-
-## socat (only for testing purposes)
-
-If you want to test Garage with a TLS frontend, socat can do it for you in a single command:
-
-```bash
-socat \
-"openssl-listen:443,\
-reuseaddr,\
-fork,\
-verify=0,\
-cert=/tmp/garage.pem" \
-tcp4-connect:localhost:3900
-```
-
-## Nginx
-
-Nginx is a well-known reverse proxy suitable for production.
-We do the configuration in 3 steps: first we define the upstream blocks ("the backends")
-then we define the server blocks ("the frontends") for the S3 endpoint and finally for the web endpoint.
-
-The following configuration blocks can be all put in the same `/etc/nginx/sites-available/garage.conf`.
-To make your configuration active, run `ln -s /etc/nginx/sites-available/garage.conf /etc/nginx/sites-enabled/`.
-If you directly put the instructions in the root `nginx.conf`, keep in mind that these configurations must be enclosed inside a `http { }` block.
-
-And do not forget to reload nginx with `systemctl reload nginx` or `nginx -s reload`.
-
-### Defining backends
-
-First, we need to tell to nginx how to access our Garage cluster.
-Because we have multiple nodes, we want to leverage all of them by spreading the load.
-
-In nginx, we can do that with the upstream directive.
-Because we have 2 endpoints: one for the S3 API and one to serve websites,
-we create 2 backends named respectively `s3_backend` and `web_backend`.
-
-A documented example for the `s3_backend` assuming you chose port 3900:
-
-```nginx
-upstream s3_backend {
- # if you have a garage instance locally
- server 127.0.0.1:3900;
- # you can also put your other instances
- server 192.168.1.3:3900;
- # domain names also work
- server garage1.example.com:3900;
- # you can assign weights if you have some servers
- # that are more powerful than others
- server garage2.example.com:3900 weight=2;
-}
-```
-
-A similar example for the `web_backend` assuming you chose port 3902:
-
-```nginx
-upstream web_backend {
- server 127.0.0.1:3902;
- server 192.168.1.3:3902;
- server garage1.example.com:3902;
- server garage2.example.com:3902 weight=2;
-}
-```
-
-### Exposing the S3 API
-
-The configuration section for the S3 API is simple as we only support path-access style yet.
-We simply configure the TLS parameters and forward all the requests to the backend:
-
-```nginx
-server {
- listen [::]:443 http2 ssl;
- ssl_certificate /tmp/garage.crt;
- ssl_certificate_key /tmp/garage.key;
-
- # should be the endpoint you want
- # aws uses s3.amazonaws.com for example
- server_name garage.example.com;
-
- location / {
- proxy_pass http://s3_backend;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header Host $host;
- }
-}
-
-```
-
-### Exposing the web endpoint
-
-The web endpoint is a bit more complicated to configure as it listens on many different `Host` fields.
-To better understand the logic involved, you can refer to the [Exposing buckets as websites](/cookbook/exposing_websites.html) section.
-Also, for some applications, you may need to serve CORS headers: Garage can not serve them directly but we show how we can use nginx to serve them.
-You can use the following example as your starting point:
-
-```nginx
-server {
- listen [::]:443 http2 ssl;
- ssl_certificate /tmp/garage.crt;
- ssl_certificate_key /tmp/garage.key;
-
- # We list all the Hosts fields that can access our buckets
- server_name *.web.garage
- example.com
- my-site.tld
- ;
-
- location / {
- # Add these headers only if you want to allow CORS requests
- # For production use, more specific rules would be better for your security
- add_header Access-Control-Allow-Origin *;
- add_header Access-Control-Max-Age 3600;
- add_header Access-Control-Expose-Headers Content-Length;
- add_header Access-Control-Allow-Headers Range;
-
- # We do not forward OPTIONS requests to Garage
- # as it does not support them but they are needed for CORS.
- if ($request_method = OPTIONS) {
- return 200;
- }
-
- proxy_pass http://web_backend;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header Host $host;
- }
-}
-```
-
-
-## Apache httpd
-
-@TODO
-
-## Traefik
-
-@TODO