Hosting a Gemini capsule on a virtual private server

Note
This article is about Gemini, the HTTP-like Internet protocol for document browsing, and not the large language model or the cryptocurrency of the same name. Nor it is about astrology.

I explained in another post that I’ve decided to embrace the use of Gemini, despite what I perceive to be its limitations. I originally set up my Gemini capsule at Ctrl-C Club (thanks, folks), but I really wanted to use my own domain name. I don’t know of any free-of-charge Gemini service that supports custom domains, or any that would allow me to experiment with dynamically-generated content, so I decided to set up my own server. I opted for a virtual private server (VPS) in the cloud rather than trying to run a server in my home, for all sorts of reasons.

In this article I explain in outline the steps involved in setting up a Gemini server in a Linux VPS. I’m assuming you’re already familiar with the Gemini protocol and the Gemtext file format, and reasonably familiar with Linux command-line tools. This article can only be an outline, because the details will depend on which VPS host you use, and which ISP, among other things.

Here are the basic steps.

1. Register a DNS domain name and get a DNS service for the new capsule

2. Buy a VPS service – the cheapest level of service is probably sufficient

3. Configure the domain’s DNS server to map to the IP of the newly-created VPS

4. On the VPS, install a Gemini server, such as Molly Brown

5. Create server certificates and configure the server

6. Configure firewall(s) to allow clients access to your server

7. Write and/or install your Gemini content

Register a domain name

For reasons that would take too long to explain, I registered the domain larsthebear.me. There are plenty of ISPs who will do this registration for you, and they differ in the services they offer. Some provide website generators, e-mail, and so on, in addition to basic domain registration. To run a Gemini capsule, all you need is a DNS service and a way to configure it, so you can point the domain name at the IP number of the Gemini server you’re about to create. Most ISPs provide some kind of web-based management console to do this, but some don’t, or charge extra for it. What other services you might need for from the ISP, that’s up to you: DNS management is the only one that’s mandatory here.

Buy a VPS

A virtual private server (VPS) is a server in the cloud to which the owner has full access, and which looks like a real machine. In practice, the same hardware might be hosting hundreds or thousands of virtual servers, which is what allows the operators to keep the costs down. I decided to use FastHosts, with its lowest grade of service – £0.83 per month. I couldn’t find anything cheaper than this, and even the lowest grade of service is adequate for a Gemini capsule, provided it isn’t under high load – and it probably won’t be, Gemini being what it is.

My VPS is running Ubuntu Linux. You can get a Windows VPS, but they’re considerably more expensive than Linux, for both licensing and resourcing reasons. Linux is fine for hosting a Gemini capsule: there are well-established Gemini servers for Linux.

When you buy a Linux VPS, you’ll get an IP number, and an initial root (administrator) password. These two pieces of information are sufficient to get started setting up the Gemini server. Still, I’d suggest waiting until the domain name registration has taken effect, and you’ve updated the DNS settings, before doing too much more work. Having a bit of patience here will save you having to do things more than once later.

As a matter of course, I always create a new, unprivileged user as my first action in a new VPS. I use this user, rather than root, as much as possible. That way I’m less likely to make an ill-considered administrative change. However, you’ll usually need to use the root account to install software.

Configure the domain’s DNS settings

The registration agent will usually provide a web-based console for this. The minimum, and sufficient, change you’ll need to make is to set the domain’s “A” record to the IP number of the new VPS.

It usually takes a few hours for DNS changes to propagate around the Internet. Once this has happened, you’ll be able to log into your new server using its hostname, rather than its IP number. You’ll also be able to use the real DNS name when you come to create server certificates, as I explain later.

Install a Gemini server

I’m using the “Molly Brown” server, because it’s been around for a while and, I hope, reasonably battle-hardened. In addition, it’s in the Ubuntu software repositories so installation is just a matter of

$ sudo apt install molly-brown

Create server certificates

The Gemini protocol mandates the use of TLS, so you’ll need a server certificate. A basic, self-signed certificate is enough: Gemini browsers (and users) aren’t particularly fussy about certificate signing.

You can generate a certificate suitable for Gemini using openssl:

$ mkdir /etc/molly-brown/certs
$ openssl req -x509 -newkey rsa:2048 -keyout /etc/molly-brown/certs/key.pem -out /etc/molly-brown/certs/cert.pem -days 3650 -nodes -subj "/CN=larsthebear.me" -addext "subjectAltName = DNS:larsthebear.me"

Naturally, you’ll need to use your own domain name in the certificate, rather than mine.

The default configuration file for Molly Brown is /etc/molly.conf. The Ubuntu installer doesn’t create this file, but it does install a sample which you can edit. The only mandatory settings are the certificate location and hostname:

CertPath = "/etc/molly-brown/certs/cert.pem"
KeyPath = "/etc/molly-brown/certs/key.pem"
Hostname = "larsthebear.me"

You’ll probably also need to set DocBase to point to the location of your Gemini capsule’s base directory – which you’ll probably put in the home directory of an unprivileged user, unless you want to use the root account to manage Gemini content.

DocBase = "/home/my_user/public_gemini"

There are many other settings you might add, and its worth reading the documentation to learn what these do.

With these settings in place, you can run the Gemini server:

$ sudo molly-brown &

In the longer term, you’ll probably want to configure it to start at boot time, using whatever tools your Linux version provides for this.

Configure the firewall

You may have to do this at the Linux level, or at the service level using an administration console or, as in my case, both. By default, Gemini uses port 1965. On Ubuntu, you can allow access to this port using ufw:

$ sudo ufw allow 1965

However, this isn’t sufficient on its own, if IP traffic doesn’t even reach your VPS. That’s why you might have to open the port at the VPS level as well. The FastMail VPS service has a section for “Firewall Policies” in its web-based administration console.

Install or edit Gemini content

I maintain my Gemini capsule on my home workstation, and use rsync to copy the whole thing to the VPS. You could edit your capsule directly on the VPS, but I wouldn’t advise that for anything except experimentation, because a cheap VPS probably won’t be backed up.

It should go without saying that you should copy/create your .gmi files in whatever directory you specified in the Gemini server configuration.

Closing remarks

My new Gemini capsule is at:

gemini://larsthebear.me/

In practice, with the lowest grade of service, my capsule doesn’t respond to clients any more quickly that it did on Ctrl-C Club. However, I’m now in a position to add CGI scripts and other dynamic content, which I couldn’t do before.