The Gemini project defines a protocol and markup for serving documents. The server runs on port 1965 by default, it responds to gemini:// URLs, it uses TLS with client certificates, and it has a simple markdown that fixes the shortcomings of Gopher pages without adding much extra. There are GUI, terminal, and command line clients already available.
My own Gemini server is at gemini://gemini.susa.net/. At least one web-based proxy has been made available by some kind soul, but I recommend using a proper client to get the full ‘other-worldliness’ experience. I’m only half-kidding here, because it’s the separation of protocol that makes Gemini potentially valuable; it’s a hostile environment for the crap that has devalued HTTP, not even inline images are supported. You have to choose to download an image, just like any other link, and that’s a matter of principle in the protocol design. Naturally, this will prevent it from ever catching on like the web, which is kind of the whole point.
If you want to publish stuff somewhere separate from the world wide web, then this seems like a good alternative. The markdown is simple, yet gives headings, paragraphs, pre-formatted blocks, lists, and links. Below is a summary, but the full specification is at https://gemini.circumlunar.space/docs/specification.html (it’s brief; it can currently be read in the time it takes to drink a coffee!)
# This would be an H1
## This would be an H2
### This would be an H3
=> https://www.susa.net Click me, I always exist on my own line.
> This line will show as a block-quote
* This is the first list item.
* This is another list item.
Pre-formatted blocks start and end with lines containing three back-ticks (```)
Anything else is just normal paragraph text, blank lines are always preserved.
The simplest Gemini client is Bash
Using ncat, it’s possible to make a request to a Gemini server with the following: –
echo -ne 'gemini://gemini.susa.net/index.gmi\r\n'|ncat --ssl gemini.susa.net 1965This results in the following on stdout. The first line is the server’s response code, the rest is my index.gmi content: –
20 text/gemini
Hello from Gemini dot Susa dot Net
=> lua_api.txt The Official Minetest Lua API for modding.
=> lua_api.gmi The Official Minetest Lua API in Gemini markup.
=> xtract_lua_api.awk My awk script to extract sections of the API.
=> petz_functions.gmi a list of member functions in the Petz mod.
=> minetest_pointed_thing.gmi my explanation of above and under nodes.
=> hexchat_no_such_device_or_address.gmi Fix HexChat Disconnected (No such device or address)
My web site is at: -
=> https://www.susa.net/wordpress/
I can be reached via SMTP at kevin@susa.netSo simple, this is a great initiative; decisions seem to have been well considered. I’m grateful! For more, see https://gemini.circumlunar.space/
A more featureful client: GemiNaut
For a server, I use agate gemserv:
I have tried agate, which I think serves static files for a single host. I then spent ages getting GLV-1.12556 running, which has lots of well considered features, but it required a lot of fiddling and hacking to get it to compile and run, so it might be too much of an admin hassle.
I have currently switched to gemserv, which seems to have similarly useful features (virtual hosts, CGI, home directories), but runs as a single binary like agate, and the Rust project builds easily with cargo. There are a couple of links to CGI examples at gemini://gemini.susa.net if you want to see the server in action.
My server needs a private key and certificate (just issued locally using openssl).
# This command created a key and certificate that's valid for any host on susa.net.
openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem -days 3650 -nodes -subj "/CN=*.susa.net"
# This command lets you view your server's certificate as human-readable text for troubleshooting.
openssl x509 -in cert.pem -textThe following is some server output, including the command line that launched the server (in this case agate).
kevin@kakapo:~/gemini$ ./agate.x86_64-unknown-linux-gnu 0.0.0.0:1965 ./content/ cert.pem key.rsa
Got request for "gemini://www.susa.net:1965/"
Got request for "gemini://www.susa.net/"
Got request for "gemini://gemini.susa.net/"
Got request for "gemini://gmi.susa.net/"
Got request for "gemini://gmi.susa.net/favicon.txt"
Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }
Got request for "gemini://gmi.susa.net:1965/"
Got request for "gemini://gmi.susa.net:1965/petz_functions"
Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }
Got request for "gemini://gmi.susa.net:1965/petz_functions.gmi"
My index.gmi file to show a little markdown.
Hello from Gemini
=> petz_functions.gmi a list of member functions in the Petz mod.
You may check out my website at: -
=> https://www.susa.net/wordpress/
```
-- Lua code to log my name minetest.log("Kevin")
```
Kevin said:
> This is quite a useable format to document Minetest mods. I think I'll use this in future.
### I'm signing off now
Good day to you sir. I bid you farewell.
If you have a gemini client, you can view this at gemini://gemini.susa.net/