Gemini is a simple protocol and markup for transmitting text pages on the internet. It is similar to http/html and improves on gopher.
With portal.mozz.us, one can surf gemini pages with a web browser.
I use gemini for the following reasons:
- the documents don't execute code
- there is minimal tracking (only ip address)
- the clients are lightweight and will that way
- the servers are lightweight
- I don't need to get a certificate from let's encrypt for my personal sites
- I can write my own server
On my phone, I tried:
- Elaho: iOS, good
- Deedum: iOS and Android, good
On the terminal, I used ncat:
The amfora tui client is also good.
Markdown to Gemini markup converter
I tried md2gemini, to install it, run:
To convert a markdown file, run:
Setting up a Gemini server
I chose to run the gmnisrv gemini server, because it is lightweight and simple to build. It only depends on the openssl library.
I run the following commands:
I keep the default configuration, so everything is installed in
I create a home directory for gmnisrv:
I generate a gemtext file with md2gemini:
I copy the default configuration file:
I edit the config file:
The default config file looks like this:
I change the tls store path, the virtual server(to my local ip address) and the root for the virtual server:
Then I start the server and test it:
I also tried the Moongem server, there is no need for a configuration file. The program takes certificate, key and document root in arguments.
Here is how to build it in debian bullseye:
It doesn't generate a certificate automatically, so I generate one with the command (replace 'URL' with the server DNS address):
To start the server, run:
The gmid gemini server works fine but it doesn't send the images on my gemini pages.
Gemini markup: Gemtext
Here's the basics of how text works in Gemtext:
- Long lines get wrapped by the client to fit the screen
- Short lines don't get joined together
- Write paragraphs as single long lines
- Blank lines are rendered verbatim
You get three levels of heading:
You get one kind of list and you can't nest them:
Here's a quote from Maciej Cegłowski:
Lines which start with ``` will cause clients to toggle in and out of ordinary rendering mode and preformatted mode. In preformatted mode, Gemtext syntax is ignored so links etc. will not be rendered, and text will appear in a monospace font.
Write links like this:
CGI configuration for gmnisrv
This section shows an example setup of cgi scripts, for more information read the man for
gmnisrvini (install the
scdoc package to convert
gmnisrvini.scd to roff:
scdoc < gmnisrvini.scd > gmnisrvini.roff && man -l gmnisrvini.roff)
- Create a route
example.comfor storing the gemtexts where cgi is off. The files in
/srv/gemini/example.comare served according to their mime types.
- Create a route
example.com/cgifor the executable programs where cgi is on. The files in
/srv/gemini/example.com/cgiare executed and everyting printed to stdout is sent as a response to the client.
example.sh script and make the script executable with
chmod 755 example.sh:
example.sh print the environment variables set by
Now it is possible to call
- On the first request,
QUERY_STRINGare empty strings
- On the second request,
PATH_INFOis an empty strings and
Text 1024 Bytes Max. The
%20strings in the query string are converted to space characters.
- On the third request,
PATH_INFOis set to
QUERY_STRINGis set to
To receive an input from client, the script should respond with
10 Enter your text:\r\n instead of
When the client sends the input, the script is called again and
QUERY_STRING is the input from the client. Eventually the script responds with
20 text/gemini\r\n+gemtext to show the result of the client request.
To make a gemcall to an input endpoint (for example:
example.com/cgi/submit), run this: