git » gofer » commit 0cf6203

diff --git a/README.md b/README.md
index 3ee1a7e..e331c45 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,9 @@ go install blitiri.com.ar/go/gofer@latest
 See the [reference config](config/gofer.yaml) for details on how to configure
 gofer, and what features are available.
 
+There are also [practical configuration examples](doc/examples.md) that cover
+the most common use cases.
+
 
 ## Contact
 
diff --git a/doc/examples.md b/doc/examples.md
new file mode 100644
index 0000000..0c547f7
--- /dev/null
+++ b/doc/examples.md
@@ -0,0 +1,126 @@
+
+# [gofer](https://blitiri.com.ar/git/r/gofer) configuration examples
+
+See the [reference config](../config/gofer.yaml) for the full list of options.
+
+
+## Static HTTP server
+
+Static HTTP server, on port `8080`, serving the contents of `/srv/www/`.
+
+```yaml
+http:
+  ":8080":
+    routes:
+      "/":
+        dir: "/srv/www/"
+```
+
+
+## Virtual domains
+
+HTTP server with different virtual domains, and redirection from
+`www.domain.com` to `domain.com`.
+
+```yaml
+http:
+  ":80":
+    routes:
+      "cats.com/":
+        dir: "/srv/cats/www/"
+      "www.cats.com/":
+        redirect: "http://cats.com/"
+
+      "elephants.com/":
+        dir: "/srv/elephants/www/"
+      "www.elephants.com/":
+        redirect: "http://elephants.com/"
+```
+
+
+## HTTPS server with autocerts and HSTS
+
+Static HTTPS server, with automatic SSL certificates (obtained via
+[Let's Encrypt](https://letsencrypt.org), and enabling
+[HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security).
+
+```yaml
+https:
+  ":443":
+    routes:
+      "/":
+        dir: "/srv/www/"
+      "www.example.com/":
+        redirect: "https://example.com/"
+
+    autocerts:
+      hosts: ["example.com", "www.example.com"]
+      email: "me@example.com"
+
+    setheader:
+      "/":
+        "Strict-Transport-Security": "max-age=63072000;"
+```
+
+## Request logging
+
+Write request logs to `/var/log/gofer/requests.log`.
+
+```yaml
+reqlog:
+  "requests.log":
+    file: "/var/log/gofer/requests.log"
+    bufsize: 16
+
+http:
+  ":80":
+    reqlog:
+      "/": "requests.log"
+    routes:
+      "/":
+        dir: "/srv/www/"
+```
+
+## Reverse HTTP proxy
+
+Proxy `http://example.com/api/` requests to another server running on
+`http://localhost:8080/`.
+
+```yaml
+http:
+  ":80":
+    routes:
+      "example.com/":
+        dir: "/srv/www/"
+
+      "example.com/api/":
+        proxy: "http://localhost:8080/"
+```
+
+## Built-in monitoring server
+
+gofer comes with a built-in monitoring HTTP server, for debugging and
+troubleshooting. \
+Do **not** expose it to the internet, it will leak a lot of information.
+
+```yaml
+control_addr: "127.0.0.1:8081"
+
+http:
+  ":8080":
+    routes:
+      "/":
+        dir: "/srv/www/"
+```
+
+
+## Raw proxy with TLS termination
+
+Listen for TLS connections on port 995, and proxy it to `127.0.0.1:110`.
+
+```yaml
+raw:
+  ":995":
+    certs: "/etc/letsencrypt/live/"
+    to: "127.0.0.1:110"
+```
diff --git a/test/test.sh b/test/test.sh
index a9e6096..79a7a74 100755
--- a/test/test.sh
+++ b/test/test.sh
@@ -235,6 +235,8 @@ if ! waitgrep -q ":8447 = 500" .01-fe.requests.log; then
 	exit 1
 fi
 
+echo "### Checking examples from doc/examples.md"
+./util/check-examples.sh
 
 echo "## Success"
 snoop
diff --git a/test/util/check-examples.sh b/test/util/check-examples.sh
new file mode 100755
index 0000000..b319e72
--- /dev/null
+++ b/test/util/check-examples.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+
+set -e
+
+. $(dirname ${0})/lib.sh
+init
+
+
+HEADER=""
+EXAMPLE=""
+IN_EXAMPLE=n
+while IFS="" read LINE; do
+	if [ "$LINE" == '```yaml' ]; then
+		# begin example
+		IN_EXAMPLE=y
+	elif [ "$LINE" == '```' ]; then
+		# end example
+		echo "  $HEADER"
+		printf "$EXAMPLE" > /tmp/gofer-example.yaml
+		cue vet ../config/gofer.schema.cue /tmp/gofer-example.yaml
+
+		HEADER=""
+		EXAMPLE=""
+		IN_EXAMPLE=n
+	elif [ "$IN_EXAMPLE" == "y" ]; then
+		# append to current example
+		EXAMPLE="$EXAMPLE\n$LINE"
+	elif [[ "$LINE" =~ ^\#+\  ]]; then
+		# found a header
+		HEADER=$( echo "$LINE" | sed "s/^\#\+ //g" )
+	fi
+done < ../doc/examples.md