Add documentation for nginx
This commit is contained in:
Quentin Dufour
parent
e342db19aa
commit
8e25a37f0e
@ -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.
|
||||
This is required as we have no other way to serve CORS headers yet.
|
||||
For our example, we will use nginx:
|
||||
|
||||
```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;
|
||||
}
|
||||
}
|
||||
```
|
||||
Check the [Configuring a reverse proxy](/cookbook/reverse_proxy.html) section to know how.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
@ -1,19 +1,142 @@
|
||||
# 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 {
|
||||
# In production you should use TLS instead of plain HTTP
|
||||
listen [::]:80;
|
||||
listen [::]:443 http2 ssl;
|
||||
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
|
||||
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;
|
||||
@ -25,8 +148,7 @@ server {
|
||||
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_pass http://web_backend;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
@ -36,4 +158,8 @@ server {
|
||||
|
||||
## Apache httpd
|
||||
|
||||
@TODO
|
||||
|
||||
## Traefik
|
||||
|
||||
@TODO
|
||||
|
||||
Loading…
Reference in New Issue
Block a user