aboutsummaryrefslogtreecommitdiff
path: root/doc/book/cookbook/reverse-proxy.md
diff options
context:
space:
mode:
authorMendes <mendes.oulamara@pm.me>2022-10-04 18:14:49 +0200
committerMendes <mendes.oulamara@pm.me>2022-10-04 18:14:49 +0200
commit829f815a897b04986559910bbcbf53625adcdf20 (patch)
tree6db3c27cff2aded754a641d1f2b05c83be701267 /doc/book/cookbook/reverse-proxy.md
parent99f96b9564c9c841dc6c56f1255a6e70ff884d46 (diff)
parenta096ced35562bd0a8877a1ee2f755be1edafe343 (diff)
downloadgarage-829f815a897b04986559910bbcbf53625adcdf20.tar.gz
garage-829f815a897b04986559910bbcbf53625adcdf20.zip
Merge remote-tracking branch 'origin/main' into optimal-layout
Diffstat (limited to 'doc/book/cookbook/reverse-proxy.md')
-rw-r--r--doc/book/cookbook/reverse-proxy.md165
1 files changed, 162 insertions, 3 deletions
diff --git a/doc/book/cookbook/reverse-proxy.md b/doc/book/cookbook/reverse-proxy.md
index 61bc7933..fb918778 100644
--- a/doc/book/cookbook/reverse-proxy.md
+++ b/doc/book/cookbook/reverse-proxy.md
@@ -100,7 +100,7 @@ server {
}
```
-## Exposing the web endpoint
+### Exposing the web endpoint
To better understand the logic involved, you can refer to the [Exposing buckets as websites](/cookbook/exposing_websites.html) section.
Otherwise, the configuration is very similar to the S3 endpoint.
@@ -140,6 +140,165 @@ server {
@TODO
-## Traefik
+## Traefik v2
+
+We will see in this part how to set up a reverse proxy with [Traefik](https://docs.traefik.io/).
+
+Here is [a basic configuration file](https://doc.traefik.io/traefik/https/acme/#configuration-examples):
+
+```toml
+[entryPoints]
+ [entryPoints.web]
+ address = ":80"
+
+ [entryPoints.websecure]
+ address = ":443"
+
+[certificatesResolvers.myresolver.acme]
+ email = "your-email@example.com"
+ storage = "acme.json"
+ [certificatesResolvers.myresolver.acme.httpChallenge]
+ # used during the challenge
+ entryPoint = "web"
+```
+
+### Add Garage service
+
+To add Garage on Traefik you should declare a new service using its IP address (or hostname) and port:
+
+```toml
+[http.services]
+ [http.services.my_garage_service.loadBalancer]
+ [[http.services.my_garage_service.loadBalancer.servers]]
+ url = "http://xxx.xxx.xxx.xxx"
+ port = 3900
+```
+
+It's possible to declare multiple Garage servers as back-ends:
+
+```toml
+[http.services]
+ [[http.services.my_garage_service.loadBalancer.servers]]
+ url = "http://xxx.xxx.xxx.xxx"
+ port = 3900
+ [[http.services.my_garage_service.loadBalancer.servers]]
+ url = "http://yyy.yyy.yyy.yyy"
+ port = 3900
+ [[http.services.my_garage_service.loadBalancer.servers]]
+ url = "http://zzz.zzz.zzz.zzz"
+ port = 3900
+```
+
+Traefik can remove unhealthy servers automatically with [a health check configuration](https://doc.traefik.io/traefik/routing/services/#health-check):
+
+```
+[http.services]
+ [http.services.my_garage_service.loadBalancer]
+ [http.services.my_garage_service.loadBalancer.healthCheck]
+ path = "/"
+ interval = "60s"
+ timeout = "5s"
+```
+
+### Adding a website
+
+To add a new website, add the following declaration to your Traefik configuration file:
+
+```toml
+[http.routers]
+ [http.routers.my_website]
+ rule = "Host(`yoururl.example.org`)"
+ service = "my_garage_service"
+ entryPoints = ["web"]
+```
+
+Enable HTTPS access to your website with the following configuration section ([documentation](https://doc.traefik.io/traefik/https/overview/)):
+
+```toml
+...
+ entryPoints = ["websecure"]
+ [http.routers.my_website.tls]
+ certResolver = "myresolver"
+...
+```
+
+### Adding gzip compression
+
+Add the following configuration section [to compress response](https://doc.traefik.io/traefik/middlewares/http/compress/) using [gzip](https://developer.mozilla.org/en-US/docs/Glossary/GZip_compression) before sending them to the client:
+
+```toml
+[http.routers]
+ [http.routers.my_website]
+ ...
+ middlewares = ["gzip_compress"]
+ ...
+[http.middlewares]
+ [http.middlewares.gzip_compress.compress]
+```
+
+### Add caching response
+
+Traefik's caching middleware is only available on [entreprise version](https://doc.traefik.io/traefik-enterprise/middlewares/http-cache/), however the freely-available [Souin plugin](https://github.com/darkweak/souin#tr%C3%A6fik-container) can also do the job. (section to be completed)
+
+### Complete example
+
+```toml
+[entryPoints]
+ [entryPoints.web]
+ address = ":80"
+
+ [entryPoints.websecure]
+ address = ":443"
+
+[certificatesResolvers.myresolver.acme]
+ email = "your-email@example.com"
+ storage = "acme.json"
+ [certificatesResolvers.myresolver.acme.httpChallenge]
+ # used during the challenge
+ entryPoint = "web"
+
+[http.routers]
+ [http.routers.my_website]
+ rule = "Host(`yoururl.example.org`)"
+ service = "my_garage_service"
+ middlewares = ["gzip_compress"]
+ entryPoints = ["websecure"]
+
+[http.services]
+ [http.services.my_garage_service.loadBalancer]
+ [http.services.my_garage_service.loadBalancer.healthCheck]
+ path = "/"
+ interval = "60s"
+ timeout = "5s"
+ [[http.services.my_garage_service.loadBalancer.servers]]
+ url = "http://xxx.xxx.xxx.xxx"
+ [[http.services.my_garage_service.loadBalancer.servers]]
+ url = "http://yyy.yyy.yyy.yyy"
+ [[http.services.my_garage_service.loadBalancer.servers]]
+ url = "http://zzz.zzz.zzz.zzz"
+
+[http.middlewares]
+ [http.middlewares.gzip_compress.compress]
+```
+
+## Caddy
+
+Your Caddy configuration can be as simple as:
+
+```caddy
+s3.garage.tld, *.s3.garage.tld {
+ reverse_proxy localhost:3900 192.168.1.2:3900 example.tld:3900
+}
+
+*.web.garage.tld {
+ reverse_proxy localhost:3902 192.168.1.2:3900 example.tld:3900
+}
+
+admin.garage.tld {
+ reverse_proxy localhost:3903
+}
+```
+
+But at the same time, the `reverse_proxy` is very flexible.
+For a production deployment, you should [read its documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) as it supports features like DNS discovery of upstreams, load balancing with checks, streaming parameters, etc.
-@TODO