Ground Control

Ground Control is a programmable Project Gemini server for Linux.

$ git clone gemini://jeffrey.cam/ground-control/

Ground Control is configured by writing request handlers in the Wren scripting language, or using built-in handlers to serve static files.

The Wren Scripting Language

Ground Control is also a general purpose Wren runtime and system library that is well suited for programs that handle I/O from many concurrent connections.

Ground Control trades POSIX compatibility for modern operating system features. All I/O is dispatched through io_uring, and TLS (after the initial handshake) is transparently handled by the kernel via ktls.

Ground Control depends on the following external libraries:

liburing
bearssl
pcre2

All external dependencies are common system libraries that can be installed through your preferred package manager. Ground Control is tested on Debian 13 Trixie. It will not run on previous versions of Debian.

Building & Installing

Ensure that all dependent libraries are installed, then run

$ make

Copy the file "ground-control" to "/usr/local/bin" or to another directory from which it can be executed.

Ensure that the Kernel TLS module is loaded.

# modprobe tls

Hosting a Static Capsule

Create a directory to hold your capsule configuration. In this directory, generate an RSA key and self signed certificate. For example, using this openssl command

$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 9999 -nodes

Create a directory called "public_gemini" in your capsule configuration directory. This directory will contain static files for ground control to serve. If you have some already, put them there now.

Create a file called "main.wren" in your capsule configuration directory and put this text in it:

var creds = Tls.loadServerCreds("cert.pem", "key.pem")

Gemini.runServer(creds, "::", 1965,
	FileServer.new("public_gemini").
        setDirListing().
        setIndexFname("index.gmi")
)

now run

$ ground-control $capsule_configuration_directory