agate 2.3.0

Very simple server for the Gemini hypertext protocol
agate-2.3.0 is not a library.

Agate

Simple Gemini server for static files

Agate is a server for the Gemini network protocol, built with the Rust programming language. Agate has very few features, and can only serve static files. It uses async I/O, and should be quite efficient even when running on low-end hardware and serving many concurrent requests.

Learn more

Installation and setup

  1. Download and unpack the pre-compiled binary.

    Or, if you have the Rust toolchain installed, run cargo install agate to install agate from crates.io.

    Or download the source code and run cargo build --release inside the source repository, then find the binary at target/release/agate.

  2. Generate a self-signed TLS certificate and private key. For example, if you have OpenSSL 1.1 installed, you can use a command like the following. (Replace the hostname with the address of your Gemini server.)

openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
    -days 3650 -nodes -subj "/CN=example.com"
  1. Run the server. You can use the following arguments to specify the locations of the content directory, certificate and key files, IP address and port to listen on, host name to expect in request URLs, and default language code(s) to include in the MIME type for for text/gemini files:
agate --content path/to/content/ \
      --key key.rsa \
      --cert cert.pem \
      --addr :::1965 \
      --addr 0.0.0.0:1965 \
      --hostname example.com \
      --lang en-US

All of the command-line arguments are optional. Run agate --help to see the default values used when arguments are omitted.

When a client requests the URL gemini://example.com/foo/bar, Agate will respond with the file at path/to/content/foo/bar. If any segment of the requested path starts with a dot, agate will respond with a status code 52, even if the file does not exist (this behaviour can be disabled with --serve-secret). If there is a directory at that path, Agate will look for a file named index.gmi inside that directory. If there is no such file, but a file named .directory-listing-ok exists inside that directory, a basic directory listing is displayed. Files or directories whose name starts with a dot (e.g. the .directory-listing-ok file itself) are omitted from the list.