Update configuration docs
This commit is contained in:
parent
5637f27b45
commit
d1f9c6d4aa
2 changed files with 78 additions and 7 deletions
|
@ -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:
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue