From f3405b6378abf29c7d1cd2bd81b6c2bdfccf0867 Mon Sep 17 00:00:00 2001
From: Quentin Dufour <quentin@deuxfleurs.fr>
Date: Thu, 4 Nov 2021 12:06:38 +0100
Subject: Doc about exposing your website

---
 doc/book/src/SUMMARY.md                    |  2 +-
 doc/book/src/cookbook/exposing_websites.md | 47 ++++++++++++++++++++++++++++++
 doc/book/src/cookbook/reverse_proxy.md     | 38 ++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 1 deletion(-)

(limited to 'doc/book')

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
-- 
cgit v1.2.3