HOWTO Setup GmCapsule

Overview

• Step 1: Install GmCapsule
• Step 2: Create Server/Cert Key
• Step 3: Create Your Folder Structure
• Step 4: Configure the Server
• Step 5: Test it Out
• Step 6: Daemonize GmCapsule

Background

I like GmCapsule as a gemini server because it's easy to install, is written in Python, supports CGI, and has support for the Titan protocol. I've been using it for a while now and @skyjake actively maintains it.

Step 1: Install GmCapsule

$ pip install gmcapsule

Step 2: Create Server Cert/Key

Step 2a: Download and Build GemCert:

$ git clone https://tildegit.org/solderpunk/gemcert.git
$ cd gemcert
$ go build main.go
$ mv main gemcert

Note: Just "go build" wasn't working for me but 'go build main.go' did, so I just renamed the file to gemcert after it built

Step 2b: Generate Cert/Key:

$ ./gemcert --server --domain localhost
$ mv localhost.crt cert.pem
$ mv localhost.key key.pem

Explanation:

• Generate a server certificate, in this case, for localhost (i.e, for local testing)
• The keys are already in pem format, but GmCapsule certificates require a specific naming convention

Step 2c: Move the Keys to Your Cert Directory

$ mkdir ~/.certs/gmcapsule/
$ mv *.pem ~/.certs/gmcapsule/

Explanation:

• Move the keys to the location specified in your ~/.gmcapsulerc (created in Step 4)
• Note: make sure you put your FULL PATH into .gmcapsulerc, and not the shortcut for home directories (i.e., ~/gritty/.certs/gmcapsule vs. /home/gritty/.certs/gmcapsule)

Step 3: Create Your Folder Structure

GmCapsule requires your content to be served out of a folder that is the same name as your domain / host, e.g., "gemini.smallweb.space/"

Example folder structure:

.
└── ~/gemini/
    ├── localhost/
    │   └── index.gmi
    └── cgi-bin/
        └── localhost/
            └── my_cgi_program

Notice how both directories have a subdirectory of "localhost" since that's my "domain" for my local computer. Of course, you'd rename to your actual domain specified in your .gmcapsulerc

Step 3a: Create index.gmi

$ vim ~/gemini/localhost/index.gmi

And drop in:

# Hello World
## Test Page

Step 4: Configure the Server

The default user location for .gmcapsulerc is ~/.gmcapsulerc. Since it doesn't exist, we'll make it.

$ touch ~/.gmcapsulerc
$ vim ~/.gmcapsulerc

A full example file can be found on the GmCapsule User Manual:

GmCapsule User Manual

Let's put in some real basic defaults to get our server going

[server]
host = localhost 
port = 1965
certs = /home/<your_user>/.certs/gmcapsule

[static]
root = /home/<your_user>/gemini/<your_domain_name>

[cgi]
bin_root = /home/<your_user>/gemini/cgi-bin/<your_domain_name>

Explanation:

• host: this is the host you generated certs for using GemCert. Multiple hosts can be specifed by using a space between them. This is why GmCapsule requires the directory name to be your domain - so it knows were to serve from
• port: gemini is typically 1965 but you can change if you like
• certs: location of the certs you generated
• root: where your main static *.gmi files are located
• bin_root: where your cgi files go (not required, but handy if you'll use them)

Step 5: Test It Out

Manually fire up the server and see what happens

$ gmcapsuled
GmCapsule v0.6.1
Configuration: /home/<your_user>/.gmcapsulerc
Init: Rewriter
Init: Git Repository Viewer
Init: CGI programs
Init: Static files
  Content directory: /home/<your_user>/gemini/{hostname}
Opening port 1965...
Server started on port 1965
5 parser(s) and 2 handler(s) started
2024-02-22 09:10:41 [0] -- gemini://localhost/
2024-02-22 09:10:50 [1] -- gemini://localhost/index.gmi

Step 5a: Open Port 1965 (if necessary)

If you're using ufw or something similar, open port 1965

$ sudo ufw allow 1965

Step 5b: Test it out

Fire up your Gemini client and navigate to your site. If you're doing local hosting, this would be: gemini://localhost/index.gmi

And you should see your index.gmi page from above:

Hello World!

Test Page

Step 6: Troubleshooting

I had an SSL issue when starting GmCapsule:

AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'

Which led me to this page:

StackOverFlow

Short answer, upgrade pyopenssl:

$ pip install -U pyopenssl cryptography

Certificate Errors

If you get certificate errors, make sure:

• you have the right domain specified
• the certificates are named properly
• the certificates are in the correct location (specified in your .gmcapsulerc)
• .gmcapsulerc "cert" path is a FULL path, NOT (~/)

Step 7: Daemonize GmCapsule

If you run the server manaully, it'll stop once you log out or end it. To get around this you would daemonize your program in order to start every time the server starts. Most systems use Systemd, so that will be detailed here.

$ sudo vim /etc/systemd/system/gmcapsule.service

and put something like this in there (modify to your install)

[Unit]
Description=GmCapsule: extensible Gemini/Titan server
After=network.target
 
[Service]
User=<your_user>
Type=simple
ExecStart=/home/<your_user>/.local/bin/gmcapsuled
Restart=always
Environment="PYTHONUNBUFFERED=1"
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=gmcapsule
 
[Install]
WantedBy=default.target

Then enable and start it:

$ sudo systemctl enable gmcapsule
$ sudo systemctl start gmcapsule

Since our service ('SysLogIdentifier') is called 'gmcapsule' we can check its status with journalctl:

$ journalctl -f -u gmcapsule

The End

And that's pretty much it. Now the hard part is making content.

The finer details of configuring GmCapsule are in the User Manual:

GmCapsule User Manual

Check out my other HOWTO that gives example CGI scripts, and describes what else you can do with your own capsule:

Managing a Capsule on a Server You Own

2024-02-22

Gritty