Home

to set up a Gemini capsule

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.

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.

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:

Which then downloaded the repo and compiled it for me.

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

2 - open the firewall

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

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:

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:

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.

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:

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.

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:

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.

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:

=>gemini://qwertqwefsday.eu/agate.gmi Agate documentation

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:

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:

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:

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

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.

Now you can decorate and flesh it out! You can find a guide to the markup language here:

=>gemini://gemini.circumlunar.space/docs/gemtext.gmi gemtext guide

I hope this helps!