💾 Archived View for altesq.net › ~evenfire › posts › 2022-07-07.gmi captured on 2023-09-08 at 16:14:40. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
Hi there! Hope you're doing well. I'll show you how to compile and use Gemserv, the Gemini server I use for serving pages on Altesq, my pubnix. It is written in Rust, and allows for a secure, yet simple program that can serve Gemini capsules from the ~/public_gemini of every member. As you can imagine, it's good for anyone who wants to start their own public access Unix server, or host for their friends or themselves. I might make a whole series on running your own pubnix in the close future.
I hope the following guide will encourage anyone who wants to run their own capsule and make the Gemini space more lively altogether with a brighter community. We really need more capsules around here, so don't be shy! I'll be glad to help anyone who is starting out, check the bottom of this page for more information.
The guide is general purposed, not only hosting for your pubnix, but also for yourself. I named it like this because Gemserv can serve multiple capsules at once in subdirectories and subdomains which is a feature that not many Gemini server software have and might be useful to anyone who wants to start a pubnix.
Before doing anything else, you should check your firewall is all okay. This includes enabling the pot 1965 over TCP.
If you use UFW:
# ufw allow 1965/tcp
If you use FirewallD:
# firewall-cmd --zone=public --add-port 1965/tcp
Gemserv is written in Rust, the programming language from Mozilla, making it quite secure. If you don't have Rust already installed, you'll have to download it. Don't use your distribution's packages as they might be outdated or not install the full or correct tool chain. We'll use RustUp.
# curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
PS. Don't get used to running scripts via curl and piping them in sh, it's bad practice and can end up in getting malware. Always verify what you run!
Go through the installation process, it should install the necessary tool chain for your respective architecture.
First, you must clone the git repository and cd into it.
$ git clone https://git.sr.ht/~int80h/gemserv/
Now you're faced with two choices. Either you can build Rust Up with CGI, if you plan to run CGI programs, like Antenna for example, or you can build it without CGI support for additional security.
Building with CGI support:
$ cargo build --release
Building without CGI support:
$ cargo build --release --no-default-features
Once it's compiled, cd to `./target/release` and you should see a `gemserv` binary. Move the Gemserv binary to `/usr/local/bin`. Et voila, it's installed! Although you're not done as you need to configure it and install the init scripts so it auto starts.
In the `init-scripts` folder, you should see two files, `gemserv.openrc` and `gemserv.service`. To install them, you have to move them to their respective folders.
For SystemD:
# mv gemserv.service /etc/systemd/system/ # systemctl daemon-reload # systemctl enable gemserv.service
For OpenRC:
# mv gemserv.openrc /etc/init.d/ # rc-update add gemserv boot
We still have to change the paths to the binary and configuration file, so keep following!
In order to not run Gemserv as root, as it can be a possible security hazard, we'll make a new user.
# useradd gemserv
Now you have to update your auto start scripts to run Gemserv in its own user.
For SystemD:
Edit `/etc/systemd/system/gemserv.service` and in the `[Service]` section add `User=gemserv`.
For OpenRC:
It'll use the user we specify in the `config.toml` file, so we'll set it below. Otherwise, it'll default to the `gemini` user.
The SystemD script doesn't have the correct path where the binary is, so we'll fix this now. If you don't use SystemD, feel free to skip.
Edit `/etc/systemd/system/gemserv.service` and in the `[Service]` section, find the line beginning with `ExecStart=`. Change it to the following:
ExecStart=/usr/local/bin/gemserv /etc/gemserv/config.toml
If you're running SystemD, you must apply the changes to the service file.
# systemctl daemon-reload # systemctl enable gemserv
Now that you've got all that of the way, the most fun part is coming, configuring! In the root directory of the git repository, you should find a `config.toml` file. I like to keep it in `/etc/gemserv/`, so we'll make that directory and give the `gemserv` user the required permissions to access it.
# mkdir /etc/gemserv/ # mv config.toml /etc/gemserv/ # chown -R gemserv:gemserv /etc/gemserv/
Now let's go together through the configuration file!
interface = [ "[::]:1965" ]
This makes Gemserv listen on both IPv4 and IPv6, port 1965. You shouldn't change this.
log = "info"
By default, Gemserv logs IPs of people that access your capsule(s). To disable that, you can set it to "warn" or "error", to show only warnings and errors respectively, without general information. "warn" shows both warnings and errors.
[[server]] hostname = "example.com" dir = "/path/to/serv" key = "/path/to/key" cert = "/path/to/cert"
This is the configuration for your capsule. Let's break it apart.
hostname = "example.com"
You should change this to your domain name. For example, "altesq.net".
dir = "/path/to/serv"
This'll be the default page one sees when accessing your capsule. You can link to other member's capsules from it, for example, check the main page of Altesq below. The path I like to use is `/opt/gemini` for it, but you can put anything you like, that contains an `index.gmi`.
key = "/path/to/key" cert = "/path/to/cert"
These are the paths to the key and certificate for your capsule. We'll do this below, so leave this unchanged at the moment.
index = "index.gmi"
This is the default file Gemserv searches in ~/public_gemini. You should leave this untouched.
lang = "en"
You should change this to the language of your capsule. If you plan to run a pubnix, I suggest leaving it as is, as there'll be people posting in all languages.
cgi = true
As you've guessed, this enables CGI. If you compiled without CGI support, set this to false.
cgipath = "/path/to/cgi-bin/"
scgi = { "/scgi" = "localhost:4000" }
cgienv = { "GIT_PROJECT_ROOT" = "/srv/git" }
These are all optional paths. If you compiled without CGI support, comment them out, otherwise change the paths to the binary locations of your CGI software, for example FastCGI or SlowCGI.
usrdir = true
If true, this looks in every user's home directory for ~/public_gemini and serves their index file. If running a pubnix, keep this true. It'll serve it at the following path: `gemini://example.com/~user/`
proxy = { path = "localhost:1966" }
proxy_all = "localhost:1967"
redirect = { "/redirect" = "/", "/newdomain" = "gemini://example.net" }
The proxy and redirects are only if you run another Gemini server on a different port or different machine. I won't go into these details today, but you're free to comment them out.
[[server]] ## server 2 hostname = "example.net" dir = "/path/to/serv/" key = "/path/to/key" cert = "/path/to/cert"
This is a duplicate server at the ends of the configuration file. You can run multiple different Gemini capsules, with different domains! If you won't do this, comment it out and save the `config.toml` as we're done.
Gemini uses TLS with the TOFU (Trust on first use) principle, so we'll need a certificate and a key for our domain. It applies to the whole domain, including subdomains and sub directories. We'll use a wonderful tool by Solderpunk called gemcert, made for this very purpose.
Git clone it, and get the Go language in order to run it. This varies from distribution to distribution, but you can just download from their main website.
Now you can generate a key and certificate with the following:
go run main.go --server --domain example.com
You'll see two files appeared in the current directory. `example.com.crt` and `example.com.key`. We'll move them to `/etc/gemserv/`
# mv example.com.crt /etc/gemserv/ # mv example.com.key /etc/gemserv/
Now to add a bit of security, so your certificates aren't read by everyone, you can make `/etc/gemserv` accessible only by the `gemserv` user.
# chmod 700 /etc/gemserv/
Now we must edit `/etc/gemserv/config.toml` and in the `[[server]]` section, find the `key=` and `cert=` lines and fill them appropriately.
Finally, the big awaited moment! Time to start Gemserv and see if it all worked.
For SystemD:
# systemctl start gemserv
For OpenRC:
# rc-service gemserv start
Common issues include failure to open the port, permissions etc., so double check those first.