gemini://jsreed5.org/log/2023/202306/20230625-how-i-operate-my-capsule.gmi

The rise of community-oriented services on Gemini, especially Bubble, has helped introduce more people to the protocol than ever before. Recently I've seen several different newcomers looking for more information on how to set up a capsule and have a more independent presence on the platform. I'll share how I do that in this log.

This is not meant to be a guide, but rather a non-technical overview of how my capsule is set up, and it's written for an audience that is not as tech-savvy. It goes more into concepts than the particulars of the technology behind them. My hope is that recent arrivals to Geminispace can find this document, see what goes into operating my capsule, and get a better sense of how easy it can be.

I self-host Rob's Gemini Capsule. This means I run the capsule software on a computer at home, and configure my Internet connection to allow people on the public Internet to connect to it. Believe it or not, this is actually the most difficult and expensive part for me to configure properly.

In order to self-host any Internet service, I need to have a static IP address from my Internet service provider, and I need a domain name to associate with that IP address. A static IP gives my home connection a unchanging numerical "address" with which other computers can find me. Unfortunately, most ISPs do not feature a static IP address for residential-class connections. I had to upgrade our home Internet plan to a business account to get one--which I planned to do anyway, as I work from home and a business plan gives me priority support from the ISP. However, an upgraded plans means I'm also paying more for my Internet service each month.

I could have simply stuck with a numerical IP address, but it's easier and safer to get a human-friendly domain name to associate with that address. This is another incurred cost: I pay a monthly fee to "purchase" (rent) the domain name "jsreed5.org" from a domain registrar. After purchasing the domain, I configured the domain with the registrar to point to the IP address of my capsule. This happens using a technology called DNS, and while the above is a massive simplification of my setup process, DNS really is that simple at its core.

I then had to configure my home router to allow people from the public Internet to access my capsule. As all routers are different and the setup process for each one is different, it won't help much to explain how I configure mine. Be aware, however, that this step requires some understanding of networking to ensure that you do not leave your home network vulnerable to cyber attacks.

If you can't or don't want to host your capsule from your own home network, you can also host it on a VPS or other external hosting provider. I have no experience with these, so I won't discuss how they're configured.

On the hardware side, my capsule runs on a small home "server"--a standard desktop computer with no graphics card and a mid-range CPU but with lots of RAM.

I built my home server using a spare tower given to me by a friend and filling it out with parts from a local electronics supply store. It was designed to host "virtual machines"--emulated computers running inside the main operating system--which is why the computer has so much RAM in it. I originally built it in order to train on some of the virtualization technologies I used at my previous job, but now I simply use it for fun.

The home server runs a Linux OS, specifically Rocky Linux 8. It currently hosts five VMs, four of which also run Rocky Linux and one of which Windows 10. My capsule runs on one of the Linux VMs.

All of this is overkill for simply running one capsule. I use it because I already had the infrastructure in place at home, and there are already many other tools I and services I use my home server for. If you just want to host a simple capsule, any old desktop or laptop computer, all the way down to the first-generation Raspberry Pi single-board computer, will give you enough horsepower to do it.

The capsule itself is powered by a Gemini server package called "Jetforce". It's written in a programming language called Python, and if you have Python installed on your computer, you can install the server using `pip`. This means Jetforce can be run on Windows as well as Linux and macOS.

Jetforce, and indeed every Gemini server software I'm aware of, is a command-line tool; there is no graphical interface with which to control the server. The operator starts the server by typing the program name on the command line, specifying options such as what hostname to use and where CGI files are located, and pressing "Enter".

My capsule VM uses Rocky Linux, which comes with a management tool called "systemd". I wrote a configuration file for systemd that starts Jetforce when the VM starts up, and automatically specifies all the options I want. This also allows me to do things such as restart the server automatically if it crashes for any reason.

I chose Jetforce because I'm already familiar with Python, and it supports CGI scripts. CGI, in a nutshell, allows my capsule to run programs when a visitor goes to certain URLs and display the output of those programs, instead of displaying the contents of flat files. Many capsules do not need or use this functionality, so if you plan to simply server static files, you don't need to worry about CGI.

In its most basic form, hosting a capsule is extremely easy. Create a directory, put some files in that directory, start up a server and point it to the directory you created, and voilà! However, if your capsule grows bigger and you want to standardize things like layouts and links, you may want to include some automation.

I use a tool called "git" to manage the files in my capsule. git is a type of tool known as "version control systems": it was originally designed to manage software source code, keeping track of all the changes made to files and enabling multiple developers to work on the code simultaneously. git is enterprise-class software and incredibly feature-rich, which I use to my advantage.

Without going too much into the details of git, I use the tool to manage my capsule directory as a git "repository". I copy that repository (and all the files inside) to my phone, my desktop computer, and other devices from which I want to be able to work on the capsule. When I make a change to my phone's copy of the capsule files, I can use git to "push" the changed files back to the VM running the capsule. Then when I log into my desktop, I can "pull" the changed files back down from the VM, and all the files on my desktop are now up to date with the files on my phone. git also has some advanced features which allow me to do things like automatically creating and updating Atom feeds for the capsule.

If you decide to host your own Gemini capsule, I hope this log gives you a better sense of what can be done with it. I t can be as easy as renting a VPS, throwing some Gemini server software onto it, copying some content into a directory, and running the server. On the other hand, the level of setup and configuration can get quite involved, depending on how far you want to take it.

Basic Linux (or Windows): how to manage files and file permissions, running programs, running in background or via services (systemd, Windows service manager, whatever your OS of choice uses)

Basic networking: DNS, IPs and ports, how to open ports both on Linux/Windows and in the network interface (router, firewall, etc.)

How I Operate My Capsule

2023-06-25