Simple gemini server written in go

orion is a small gemini server written in go. It’s intended as an easy-to-use, containerized or standalone, secure yet simple gemini server.

orion is in a good working condition and runs my own capsule since some time already without any issues. The project is hosted on GitHub, where you also find the container packages for docker and podman.

Project status

The program runs stable and is post-alpha. I’m running my own capsule as a podman container since months without any usses. However pull-request and bug reports are very welcome. The documentation can be found on the GitHub project page (Start with the README there).

Quickstart guide

In this guide we will deploy orion as our first gemini server as a podman container. All commands should work with docker as well.


  • A Linux machine with podman or docker

In this guide I’m assuming we are using the /srv/orion directory for our configuration and data files. This directory can be of course changed to your needs. In particular the directory structure we will be using looks as follows

  /srv/orion                                # Main program directory
  + /srv/orion/conf                         # Configuration directory
    + /srv/orion/conf/orion.conf            # orion configuration file
    + /srv/orion/conf/orion.key             # TLS key file
    + /srv/orion/conf/orion.cert            # TLS certificate
  + /srv/orion/data                         # Data directory
    + /srv/orion/data/index.gmi             # Index page

Step-by-step guide

1. Create our configuration file

Use the provided orion.conf example file from the GitHub repository as a template and configure it to your needs. For your first container you might want to take the following template:

## orion configuration file for a containerized deployment
## lines starting with a '#' are comments and will be ignored

## Server hostname and listen address
# Bind ':1965' will bind to any IP address and port 1965
Bind = :1965

## TLS certificate
## Note: Those files will be loaded before chroot!
Certfile = orion.crt
Keyfile = orion.key

## Content directory
ContentDir = /data

2. Create certificates

gemini requires TLS, but most clients are just working fine with self-signed certificates. For a quick start guide, a simple self-signed certificate works just fine. Create your first certificate with make cert in the orion repository or manually by using

openssl genrsa -out orion.key 2048
openssl req -x509 -nodes -days 3650 -key orion.key -out orion.crt

To avoid certificate issues, ensure that you set the common name to the hostname of your gemini server.

Ensure the key and certificate file end up in our /srv/orion/conf directory.

3. Put some data there …

Crate the /srv/orion/data directory and the /srv/orion/data/index.gmi file. The later one can be a simple text file containing just a bare minimum example:

Hello gemini! This is an example gemini file just to test if the server is working properly

4. Run our container

podman run -d --name orion -v /srv/orion/conf:/conf -v /srv/orion/data:/data -p 1965:1965 --memory 128M ghcr.io/grisu48/orion:latest
docker run -d --name orion -v /srv/orion/conf:/conf -v /srv/orion/data:/data -p 1965:1965 ghcr.io/grisu48/orion:latest

This should run our orion container with podman/docker and you should be able to connect to it via your favorite gemini client. I used e.g. amfora, but any will do.

5. Celebrate

Congratulations! You have successfully deployed your first gemini server using orion. You are awesome!

Origin and Credits

orion has been inspired by the titan2 gemini server, but is intended to run as a docker/podman container or as a secure standalone with only minimal configuration needed.

Licensed under CC BY-NC-SA 4.0
Last updated on Aug 13, 2022 16:55 +0200