twins/CONFIGURATION.md

`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.

When accessing a directory the file `index.gemini` or `index.gmi` is served.

### Path attributes

#### Root

Serve static files from specified root directory.

Directory listing may be enabled by adding `listdirectory: true`.

#### 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: :1965

# TLS certificates
certificates:
  -
    cert: /home/gemini.rocks/data/cert.crt
    key: /home/gemini.rocks/data/cert.key

# Hosts and paths to serve
hosts:
  gemini.rocks:
    -
      path: /sites
      root: /home/gemini.rocks/data/sites
      listdirectory: true
    -
      path: ^/(help|info)$
      root: /home/gemini.rocks/data/help
    -
      path: ^/proxy-example$
      proxy: gemini://localhost:1966
    -
      path: ^/cmd-example$
      command: uname -a
    -
      path: /
      root: /home/gemini.rocks/data/home
  twins.rocketnine.space:
    -
      path: /sites
      root: /home/twins/data/sites
    -
      path: /
      root: /home/twins/data/home
```