forked from Deuxfleurs/garage
Add documentation for nginx
This commit is contained in:
parent
e342db19aa
commit
8e25a37f0e
3 changed files with 133 additions and 35 deletions
doc/book/src
|
@ -253,35 +253,7 @@ Make sure you (will) have a corresponding DNS entry for them.
|
||||||
|
|
||||||
Now we will configure a reverse proxy in front of Garage.
|
Now we will configure a reverse proxy in front of Garage.
|
||||||
This is required as we have no other way to serve CORS headers yet.
|
This is required as we have no other way to serve CORS headers yet.
|
||||||
For our example, we will use nginx:
|
Check the [Configuring a reverse proxy](/cookbook/reverse_proxy.html) section to know how.
|
||||||
|
|
||||||
```nginx
|
|
||||||
server {
|
|
||||||
# In production you should use TLS instead of plain HTTP
|
|
||||||
listen [::]:80;
|
|
||||||
|
|
||||||
server_name peertube-video.web.garage peertube-playlist.web.garage;
|
|
||||||
|
|
||||||
location / {
|
|
||||||
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 request to Garage
|
|
||||||
# as it does not know how to interpret them.
|
|
||||||
# Instead, we simply answers 200.
|
|
||||||
if ($request_method !~ ^(GET|HEAD)$ ) {
|
|
||||||
return 200;
|
|
||||||
}
|
|
||||||
|
|
||||||
# If your do not have a Garage instance on the reverse proxy, change the URL here.
|
|
||||||
proxy_pass http://127.0.0.1:3902;
|
|
||||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
||||||
proxy_set_header Host $host;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Now make sure that your 2 dns entries are pointing to your reverse proxy.
|
Now make sure that your 2 dns entries are pointing to your reverse proxy.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# Exposing websites
|
# Exposing buckets as websites
|
||||||
|
|
||||||
You can expose your bucket as a website with this simple command:
|
You can expose your bucket as a website with this simple command:
|
||||||
|
|
||||||
|
|
|
@ -1,19 +1,142 @@
|
||||||
# Configuring a reverse proxy
|
# 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
|
||||||
|
|
||||||
|
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
|
```nginx
|
||||||
server {
|
server {
|
||||||
# In production you should use TLS instead of plain HTTP
|
listen [::]:443 http2 ssl;
|
||||||
listen [::]:80;
|
ssl_certificate /tmp/garage.crt;
|
||||||
|
ssl_certificate_key /tmp/garage.key;
|
||||||
|
|
||||||
# We
|
# 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
|
server_name *.web.garage
|
||||||
example.com
|
example.com
|
||||||
my-site.tld
|
my-site.tld
|
||||||
;
|
;
|
||||||
|
|
||||||
location / {
|
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-Allow-Origin *;
|
||||||
add_header Access-Control-Max-Age 3600;
|
add_header Access-Control-Max-Age 3600;
|
||||||
add_header Access-Control-Expose-Headers Content-Length;
|
add_header Access-Control-Expose-Headers Content-Length;
|
||||||
|
@ -25,8 +148,7 @@ server {
|
||||||
return 200;
|
return 200;
|
||||||
}
|
}
|
||||||
|
|
||||||
# If your do not have a Garage instance on the reverse proxy, change the URL here.
|
proxy_pass http://web_backend;
|
||||||
proxy_pass http://127.0.0.1:3902;
|
|
||||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
proxy_set_header Host $host;
|
proxy_set_header Host $host;
|
||||||
}
|
}
|
||||||
|
@ -36,4 +158,8 @@ server {
|
||||||
|
|
||||||
## Apache httpd
|
## Apache httpd
|
||||||
|
|
||||||
|
@TODO
|
||||||
|
|
||||||
## Traefik
|
## Traefik
|
||||||
|
|
||||||
|
@TODO
|
||||||
|
|
Loading…
Reference in a new issue