twins-upstream/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.

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 to get a certificate from Let's Encrypt for a domain.

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

# 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