aboutsummaryrefslogtreecommitdiff
path: root/doc/book
diff options
context:
space:
mode:
authorQuentin Dufour <quentin@deuxfleurs.fr>2021-11-04 12:06:38 +0100
committerQuentin Dufour <quentin@deuxfleurs.fr>2021-11-08 12:20:40 +0100
commitf3405b6378abf29c7d1cd2bd81b6c2bdfccf0867 (patch)
tree335cd2b089f981d126fc3e3712cad5e35e8e550a /doc/book
parent860ccf281175b50aaaf66453cfc408ea8c1e70e2 (diff)
downloadgarage-f3405b6378abf29c7d1cd2bd81b6c2bdfccf0867.tar.gz
garage-f3405b6378abf29c7d1cd2bd81b6c2bdfccf0867.zip
Doc about exposing your website
Diffstat (limited to 'doc/book')
-rw-r--r--doc/book/src/SUMMARY.md2
-rw-r--r--doc/book/src/cookbook/exposing_websites.md47
-rw-r--r--doc/book/src/cookbook/reverse_proxy.md38
3 files changed, 86 insertions, 1 deletions
diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md
index a0a111fd..90395f18 100644
--- a/doc/book/src/SUMMARY.md
+++ b/doc/book/src/SUMMARY.md
@@ -7,8 +7,8 @@
- [Cookbook](./cookbook/index.md)
- [Building from source](./cookbook/from_source.md)
- [Integration with systemd](./cookbook/systemd.md)
- - [Configuring a reverse proxy](./cookbook/reverse_proxy.md)
- [Exposing buckets as websites](./cookbook/exposing_websites.md)
+ - [Configuring a reverse proxy](./cookbook/reverse_proxy.md)
- [Production Deployment](./cookbook/real_world.md)
- [Recovering from failures](./cookbook/recovering.md)
diff --git a/doc/book/src/cookbook/exposing_websites.md b/doc/book/src/cookbook/exposing_websites.md
index 58e1f018..96a9aebe 100644
--- a/doc/book/src/cookbook/exposing_websites.md
+++ b/doc/book/src/cookbook/exposing_websites.md
@@ -1 +1,48 @@
# Exposing websites
+
+You can expose your bucket as a website with this simple command:
+
+```bash
+garage bucket website --allow my-website
+```
+
+Now it will be **publicly** exposed on the web endpoint (by default listening on port 3902).
+
+Our website serving logic is as follow:
+ - Supports only static websites (no support for PHP or other languages)
+ - Does not support directory listing
+ - The index is defined in your `garage.toml`. ([ref](/reference_manual/configuration.html#index))
+
+Now we need to infer the URL of your website through your bucket name.
+Let assume:
+ - we set `root_domain = ".web.example.com"` in `garage.toml` ([ref](/reference_manual/configuration.html#root_domain))
+ - our bucket name is `garagehq.deuxfleurs.fr`.
+
+Our bucket will be served if the Host field matches one of these 2 values (the port is ignored):
+
+ - `garagehq.deuxfleurs.fr.web.example.com`: you can dedicate a subdomain to your users (here `web.example.com`).
+
+ - `garagehq.deuxfleurs.fr`: your users can bring their own domain name, they just need to point them to your Garage cluster.
+
+You can try this logic locally, without configuring any DNS, thanks to `curl`:
+
+```bash
+# prepare your test
+echo hello world > /tmp/index.html
+mc cp /tmp/index.html garage/garagehq.deuxfleurs.fr
+
+curl -H 'Host: garagehq.deuxfleurs.fr' http://localhost:3902
+# should print "hello world"
+
+curl -H 'Host: garagehq.deuxfleurs.fr.web.example.com' http://localhost:3902
+# should also print "hello world"
+```
+
+Now that you understand how website logic works on Garage, you can:
+
+ - make the website endpoint listens on port 80 (instead of 3902)
+ - use iptables to redirect the port 80 to the port 3902:
+ `iptables -t nat -A PREROUTING -p tcp -dport 80 -j REDIRECT -to-port 3902`
+ - or configure a [reverse proxy](reverse_proxy.html) in front of Garage to add TLS (HTTPS), CORS support, etc.
+
+You can also take a look at [Website Integration](/connect/websites.html) to see how you can add Garage to your workflow.
diff --git a/doc/book/src/cookbook/reverse_proxy.md b/doc/book/src/cookbook/reverse_proxy.md
index 658f8421..b4674852 100644
--- a/doc/book/src/cookbook/reverse_proxy.md
+++ b/doc/book/src/cookbook/reverse_proxy.md
@@ -1 +1,39 @@
# Configuring a reverse proxy
+
+## Nginx
+
+```nginx
+server {
+ # In production you should use TLS instead of plain HTTP
+ listen [::]:80;
+
+ # We
+ server_name *.web.garage
+ example.com
+ my-site.tld
+ ;
+
+ 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 requests to Garage
+ # as it does not support them but they are needed for CORS.
+ if ($request_method = OPTIONS) {
+ 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;
+ }
+}
+```
+
+
+## Apache httpd
+
+## Traefik