GmCapsule: Extensible Gemini/Titan Server

GmCapsule is a Gemini server written in Python.

Extensibility is achieved with Python modules that get loaded at launch from the configured directories. A set of built-in extension modules is provided for common functionality like CGI and for serving static files.

The supported protocols are Gemini and Titan. Both are accepted via the same TCP port.

GmCapsule can be used in a few different ways:

• You can run it as-is for serving static files.
• You can use CGI programs to generate dynamic content and/or process queries and uploads. As an extreme example, you could attach a CGI program to the path /* and generate the entire capsule procedurally with it.
• You can use the included extension module "gitview" to make local Git repositories viewable via Gemini.
• You can write new extension modules that run as part of the server process for advanced use cases. For example, this enables the use of additional worker threads and caching state in memory.

`gmcapsuled` is a simple command line utility for loading a configuration file and running the server. Use the `--help` option to see usage instructions.

Installation

Use pip to install "gmcapsule"

Alternatively, you can clone the Git repository and run the server without installing the Python module.

See also

README (includes version history)

User Manual

s/GmCapsule

Issue tracker: bugs and feature requests

Git Repository (license: BSD-2-Clause)

CGI examples: Titan

These examples assume `gmcapsuled` running on localhost.

Here is a simple CGI Python script that we'll use:

#!/usr/bin/python3
import os
import sys

titan_data = sys.stdin.read()

print("20 text/gemini\r")
print("Client cert hashes:", os.getenv('REMOTE_IDENT'))
print("Titan token:", os.getenv('TITAN_TOKEN'))
print("You uploaded %d bytes." % len(titan_data))

Method 1: CGI entry point in server config

Place the above script file anywhere you'd like, say "scripts/hello.py", and add this to the server config:

[cgi.hello]
protocol = titan
path = /hello-world
command = /usr/bin/python3 scripts/hello.py

(file paths are relative to where you start `gmcapsuled`)

Then open "titan://localhost/hello-world" in the client to start an upload.

Method 2: CGI bin_root

The advantage of setting the `bin_root` is that you can add and remove scripts in your CGI directory without restarting the server.

Normally executables inside the bin_root are assumed to be Gemini CGI scripts. To make them use Titan, append ",titan" to the executable name. So, let's create a bin_root directory called "./cgi-bin", and your script should be named:

./cgi-bin/localhost/hello-world,titan

Don't forget to set the file as executable.

The bin_root is configured in the server config:

[cgi]
bin_root = ./cgi-bin

You can then open "titan://localhost/hello-world" in the client to start an upload.

Methods 1 and 2 are mutually exclusive, you can choose which one works best for you.

Method 3: Extension module

It's actually quite simple to create a simple Titan upload handler via a Python extension module. Add a custom modules directory in the server config:

[server]
modules = ./mymod

Create this Python source file as "./mymod/50_hello.py":

def titan_upload_handler(req):
    response = 'Client cert hash: ' + req.identity.fp_cert
    response += '\nYou uploaded %d bytes.\n' % len(req.content)
    return response


def init(capsule):
    """Extension module initialization."""    
    capsule.add('/titan-hello', 
                titan_upload_handler, 
                protocol='titan')

Open "titan://localhost/titan-hello" to start the upload.