Browse Source

Update configuration docs

master
Trevor Slocum 2 years ago
parent
commit
d1f9c6d4aa
  1. 82
      CONFIGURATION.md
  2. 3
      README.md

82
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.
### Path attributes
#### Root
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.
Paths are matched in the order they are provided.
#### Command
When accessing a directory `index.gemini` or `index.gmi` is served.
Serve output of system command.
# config.yaml
# Example config.yaml
```yaml
# Address to listen on
listen: 0.0.0.0:1965
listen: :1965
# TLS certificates
certificates:

3
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

Loading…
Cancel
Save