-- Leo's gemini proxy
-- Connecting to gemini.smallweb.space:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini
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
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.
$ pip install gmcapsule
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)
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
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:
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)
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
I had an SSL issue when starting GmCapsule:
> AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'
Which led me to this page:
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 (~/)
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
And that's pretty much it. Now the hard part is making content.
The finer details of configuring GmCapsule are in the User Manual:
Check out my other HOWTO that gives example CGI scripts, and describes what else you can do with your own capsule:
2024-02-22
Gritty
-- Response ended
-- Page fetched on Mon May 13 00:52:55 2024