Update configuration docs

This commit is contained in:
Trevor Slocum 2020-10-30 17:29:25 -07:00
parent 5637f27b45
commit d1f9c6d4aa
2 changed files with 78 additions and 7 deletions

View File

@ -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:

View File

@ -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