💾 Archived View for dio9sys.fun › writeups › howtoserver › index.gmi captured on 2023-11-14 at 07:41:26. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-05-24)
-=-=-=-=-=-=-
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.
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!
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:
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.
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:
[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
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.
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.
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:
So, agate runs from a LOT of flags in the terminal. Let's go over what we want to accomplish:
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:
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
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:
I hope this helps!