2023-03-11

Adding cassini gemring server to bubblewrapped services (bws)

After adding a minimal finger daemon[a] to bubblewrapped servies (bws)[b] I set out to add cassini --- a specialized gemini server implementing a gemini ring. It is written in Go by Sol Fisher Romanoff[c].

Gemini Ring or Orbit

A web ring is a doubly linked list of sites, which can be traversed or examined in full on the ring server. So naturally this idea was adopted in gemini space as well. Some time ago I had collected terms from gemini space[d]. The term orbit was used in place of a gemini ring or gemring for short.

A Gemini Ring Server

As explained, a gemring is a way, to connect a series of capsules. Every site features a link to the previous and next site in the gemring. The gemring server hosts that list of sites. Going to the next site actually calls the gemring server including the current sites "name", i.e. the name used as key in the list on the gemring server. The gemring server responds with a redirect to the next site in the list.

In order to add a new capsule to the gemring, the operator of the gemring server will add a key and the sites URL to the list, and report the key string back to the owner of the site. The owner of the site can then add links to their capsule, pointing to the previous or next site, a random site in that list, or the index, possibly featuring a full list of sites belonging to the gemring.

Adding Cassini

build cassini --- well only few things come prepackaged with bws so far. You or your software savvy friend needs git to receive the sources, a working golang compiler, plus an internet connection, because "go build" will download additional sources from elsewhere. Useful, but creepy at the same time.
in ~/services create a subdirectory named cassini or similar
in there create subdirs ./bin/linux-$(uname -m) ./pub ./cert
copy the executable as ./bin/linux-$(uname -m)/cassini
create a key/certificate pair in ./cert in .pem format --- this is missing from the docs, so I stole the line from the documentation coming with the agate gemini server. This might be not as good or even wrong, but I do not know better at this point. The certificate expires in 10 years, at which point I will have forgotten about it anyway. Adjust to your liking.
create ./pub/index.gmi to explain the ring/orbit and optionally list the sites.
create ./pub/ring.txt holding the participant sites in the ring --- the example file lists three well known sites, so you can start exerimenting. I found that starting the name with '~' (tilde) breaks the whole thing, probably because ~username is handled differently by the gemini servers URL parsing.
create ./start.sh --- all these items need to be referenced upon start of cassini. Additionally I needed to replace the default port number (1965) with something else, because that port was already in use. The script is copied from bws examples, just the last line is new. Please note the single quotes around 'EOF', they are essential. Otherwise all $VAR strings are replaced.
if your system has a firewall configured, you may need to allow your chosen port to be accessed from outside the system.
test cassini by starting it manually. Then start it as a member of your collection of bubblewrapped services.
If all is well, register cassini in ~/services/start.

The following commands are for you inspiration, don't follow them blindly.

mkdir src; cd src
git clone https://git.sr.ht/~sfr/cassini
cd cassini; go build
cd ~

cd ~/services
mkdir gemring-cassini; cd gemring-cassini
mkdir -p ./bin/linux-$(uname -m) ./pub ./cert
cp ~/src/cassini/cassini ./bin/linux-$(uname -m)/cassini
chmod 0755 ./bin/linux-$(uname -m)/cassini
cd ./cert
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650 -nodes -subj "/CN=your.host.name.on.net"
cd ..

cat <<EOF > pub/index.gmi
# cassini gemring @ your.host.name.on.net

This gemring or orbit is about ???
Send requests to ???

List of registered capsules:

{{ list }}

Have the appropriate amount of fun.

Powered by cassini
=> https://git.sr.ht/~sfr/cassini
EOF

cat <<EOF > pub/ring.txt
antenna gemini://warmedal.se/~antenna/
cosmos gemini://skyjake.fi/~Cosmos/
midnight gemini://midnight.pub/
EOF

cat <<'EOF' > start.sh
#!/bin/sh

OS="$(uname -s)"
PLATFORM="$(uname -m)"
BIN="unknown"

if test "$OS" = "Linux"; then
  BIN="linux-$PLATFORM"
elif test "$OS" = "Darwin"; then
  BIN="macos-$PLATFORM"
fi

./bin/$BIN/cassini --port 1966 --cert ./cert/cert.pem --key ./cert/key.pem --list ./pub/ring.txt --index ./pub/index.gmi
EOF
chmod 0755 start.sh

cd ..
echo '~/services/bws start gemring-cassini' >> start

After all this you host a gemring. Now on to fill it with interesting things!

Whacky Ideas

While doing this I thought, well, I can create a detailed list of documents found in gemini space. What is called "user name" in the documentation is a mere key to said entry. So I should be able to implement the equivalent of my Ribbons[e] using this technology as well, i.e. a traversable list of documents within my capsule. I just need to add the appropriate links everywhere.

One could also try to write episodes of a story, where each chapter is hosted elsewhere, written by the owner of that capsule, and thus create funny or intriguing text, crowd edited and everything. The owner of the ring/orbit server is the one to decide about the selection and their order. The owner might even resort to hosting copies to activate when capsules get lost. And they do get lost all the time.

The cassini/huygens space mission was launched in 1997, so that might suit you as an alternate port number.

Cheers,

~ew

References

[a] Adding a minimal fingerd to bubblewrapped services (bws)

[b] Simpler Linux self-hosting with tmux and bubblewrap

[c] git.sr.ht/~sfr/cassini

[d] Terms in Gemini Space I like

[e] Towards a proper FlightLog: Ribbons (was: Colored Lines)

Home