How to set up a Gemini capsule

Intro

Hello!  Setting up a gemini capsule can be fun and rewarding, and it's not too hard!

However, there are some tricky parts that stumped me for a bit when I was starting mine.

I figured, since I ran into trouble, I might as well write a guide on how to host your
own gemini capsule for anyone running into similar problems.

What server to use?

Personally, I used agate.  It's easy to install and written in rust, which is one of
my favorite languages.  There are tons of options to choose from though, and I won't
tell you if one is specifically right for you.

Step 1 - install the server

Since I used agate, which is written in rust, and I have rust installed on my machine,
I installed it using:

cargo install agate

Which then downloaded the repo and compiled it for me.

For other server software, check their git page.  They usually have really good instructions!

Step 2 - open the firewall

Okay, this one is tricky, so I'll split this into two smaller parts.

Part 1 - open the firewall in firewalld

If you are using Fedora, CentOS, RHEL or Ubuntu server, it's likely you use firewalld to handle
your firewall needs.

To confirm, run the following command:

sudo firewall-cmd --list-all

Do you see a list of stuff?  Great!

Do you see an error about not knowing the firewall-cmd command?  Less great!  You may need to
check the firewall documentation for your distro of choice.  For this guide, I'm assuming you
are using firewalld.

Gemini by default runs on port 1965.  You'll want to open that port.  Personally, I like to
open on both tcp and udp just in case I want to do some funkiness with streaming protocols
but, if all you want is gemini, you can probably do well just by opening the port on tcp.

To open port 1965 on tcp, run the following command:

sudo firewall-cmd --permanent --add-port=1965/tcp

So what does all this do?  Let's go over it.

🌼 sudo : run as root
🌼 firewall-cmd : firewalld utility
🌼 --permanent : make your firewall change permanent.  Important!
🌼 --add-port : argument to open a port on the firewall
🌼 =1965/tcp : specify that the port you want to add is port 1965, and specifically for tcp

You should see "Success" in your terminal if all goes smoothly.  If you run into permissions
errors, make sure you're in sudoers or wheel group on your machine.

Part 2 - set up a socket for systemd

Opening a port is cool, but if you try to telnet into your machine on that port you'll get
connection refused errors.  This is because we have to set up a socket.

Socket files may differ from distro to distro, but a good place to check is:
/usr/lib/systemd/system/

Now run ls and you should see a number of files with a .socket extension.

For simplicity, I like to just copy one of the known socket files and rename it, but to make it easier
on you here's a simple socket file that works:

run sudo nano agate.socket and enter the following:

[Unit]
Description=Agate gemini server

[Socket]
ListenStream=1965
Accept=yes

[Install]
WantedBy=sockets.target

-------------------------

So, what exactly does this do?  Let's go over it

🌼 [Unit] : metadata section
🌼 Description=Agate gemini server : quick description of the socket in case we forget what it is later
🌼 [Socket] : the real meat of the socket file, this is where you determine connection stuff
🌼 ListenStream=1965 : This means that your server will listen for connections on port 1965
🌼 Accept=yes : accept all connections from machines on port 1965
🌼 [Install] : parameters for running the socket
🌼 WantedBy=sockets.target : this is a file that the sockets service will read

Okay, now that we've got this file, run the following commands:
sudo systemctl enable agate.socket
sudo systemctl start agate.socket

This should open the socket for us.

Okay, if that all worked then we're ready for step 3.

Step 3 - Write a file

You're going to want to have some kind of file to serve so you can test your capsule.  By default,
gemini clients look for a file called index.gmi.

You can place this file anywhere, but I like to put it in ~/gemini/ for ease of access.  Some people
prefer to put it in /var/gemini/

so, let's run the following commands:
mkdir ~/gemini
cd ~/gemini
nano index.gmi

Okay, we've now got an index file.  Let's put something in it.  it can be anything, just put some text down.

I wrote "uwu" and then saved and closed the file, and then edited it later in Gemtext markup language until
it became my home page.

If you're in the home directory, the default permissions should be ok.  If you're writing into /var/gemini,
you will want to run nano as root and then use chmod to make sure non-root users have read access for the file.

You can get more granular for your file permissions, but this is just a quick set up guide and you can harden it
once you know it works.

Step 4 - run the server

Okay, now is the fun part :)

There are many ways to set up the server.  Some people will write a service profile for the server to enable it in
systemd, some people will make a dedicated service user and run it there.

For the purposes of quick testing and making sure everything works, we're just going to run it in the terminal as
a background process.

For reference, here's the agate documentation:

https://github.com/mbrubeck/agate

So, agate runs from a LOT of flags in the terminal.  Let's go over what we want to accomplish:
🌼 We need to set where it pulls the content from
🌼 We need to set up listening
🌼 We need to set a hostname if we have one
🌼 We will want to set the language used by the server
🌼 We will want to run this in the background so we can do other things at the same time

Fortunately, the agate documentation has this all laid out for us.  I ran into issues trying to run it on ipv6
and ipv4 at the same time, so I ommitted the ipv6 line and went with ipv4 only.

Here's the command I ran to get my server started:

agate --content ~/gemini/ --addr 0.0.0.0:1965 --hostname dio9sys.fun --lang en-US &

Let's go over this:
🌼 agate : name of the server software
🌼 --content ~/gemini/ : where to pull the pages from
🌼 --addr 0.0.0.0:1965 : listen for any IP addresses (0.0.0.0 is shorthand for this) on port 1965
🌼 --hostname dio9sys.fun : if you have a DNS address associated with your server, replace dio9sys.fun with your domain name
🌼 --lang en-US : set the language to US english
🌼 & : send the process to the background

This should be working now.  You should see a line about it listening.

If not, you may need to tweak the arguments, check your socket file and make sure your filewall has the appropriate port open.

If you want to check the server with more verbosity, run:
jobs -l

then you will see the jobs running in the background.  In my case, the only job running is agate, so it has a number of 1

Pull it to the front with this command:
fg %1

Since my jobs only run agate, I can run fg %1 to pull the first job to the foreground.  If you have several jobs running, you
will want to change %1 to %n with n being the job number listed from running job -l

Step 5 - test the server

Now let's see if it's working!

Go to a compatible browser on a computer that is NOT your server and try it.  You should see your gemini capsule now!

If you do not, you may want to check all your settings, reference them against this guide and see if you're missing anything.




I hope this helps!