Update configuration docs

CONFIGURATION.md

@@ -1,20 +1,88 @@
+`twins` requires a configuration file to operate. By default, it is loaded from
+`~/.config/twins/config.yaml`. You may specify a different location via the
+`--config` argument.
+
+
+# Configuration options
+
+## Listen
+
+Address to listen for connections on in the format of `interface:port`.
+
+### Listen on localhost
+
+`localhost:1965`
+
+### Listen on all interfaces
+
+`:1965`
+
+## Certificates
+
+At least one certificate and private key must be specified, as Gemini requires
+TLS.
+
+### localhost certificate
+
+Use `openssl` generate a certificate for localhost.
+
+```bash
+openssl req -x509 -out localhost.crt -keyout localhost.key \
+  -newkey rsa:2048 -nodes -sha256 \
+  -subj '/CN=localhost' -extensions EXT -config <( \
+   printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
+```
+
+### Domain certificate
+
+Use [certbot](https://certbot.eff.org) to get a certificate from [Let's Encrypt](https://letsencrypt.org) for a domain.
+
+```bash
+certbot certonly --config-dir /home/www/certs \
+  --work-dir /home/www/certs \  
+  --logs-dir /home/www/certs \
+  --webroot \
+  -w /home/www/gemini.rocks/public_html \
+  -d gemini.rocks \
+  -d www.gemini.rocks
+```
+
+Provide the path to the certificate file at `certs/live/$DOMAIN/fullchain.pem`
+and the private key file at `certs/live/$DOMAIN/privkey.pem` to twins.
+
+## Hosts
+
+Hosts are defined by their hostname followed by one or more paths to serve.
+
 Paths may be defined as fixed strings or regular expressions (starting with `^`).
 
+Paths are matched in the order they are defined.
+
 Fixed string paths will match with and without a trailing slash.
 
-Serve entries have either a `root` path or `proxy` URL. When a `root` path is
-provided static files and directories are served from that location. When a
-`proxy` URL is provided requests are forwarded to the Gemini server at that URL.
+When accessing a directory the file `index.gemini` or `index.gmi` is served.
 
-Paths are matched in the order they are provided.
+### Path attributes
 
-When accessing a directory `index.gemini` or `index.gmi` is served.
+#### Root
 
-# config.yaml
+Serve static files from specified root directory.
+
+#### Proxy
+
+Forward request to Gemini server at specified URL.
+
+Use the pseudo-scheme `gemini-insecure://` to disable certificate verification.
+
+#### Command
+
+Serve output of system command.
+
+# Example config.yaml
 
 ```yaml
 # Address to listen on
-listen: 0.0.0.0:1965
+listen: :1965
 
 # TLS certificates
 certificates:

README.md

@@ -4,6 +4,9 @@
 
 [Gemini](https://gemini.circumlunar.space) server
 
+**Warning:** The twins configuration format is still under development.
+Breaking changes may be made.
+
 ## Features
 
 - Serve static files