Making BenTasker.co.uk Available As A Gemini Capsule
`www.bentasker.co.uk` has long been available via Tor and as an I2P Eepsite.
Although access via those networks requires appropriate software, the only real change is the transport layer: the site still ultimately talks HTTP and serves HTML to the user's browser. The site even _looks the same_.
This time, though, is different: my posts are now available as a Gemini Capsule (`gemini://gem.bentasker.co.uk`), serving gemtext over Gemini Protocol.
One of the things that I noticed while browsing around Gemspace is how _unintrusive_ the browsing experience is:
* no javascript
* no popups or modals
* no autoplaying videos
* there isn't _even_ site specific UI design (gemtext is rendered however your browser is configured to display it).
I found that this led to engaging with the text much more. Without all the distractions that make up the modern web, the focus really is on the content itself.
This post describes getting my Gemini Capsule up and running.
* * *
### What Changes?
Gemini doesn't use HTML. Instead, it uses gemtext which looks a lot like a very stripped dialect of markdown:
# This is a title
## This is a subheading
This is a paragraph of text, but also a good time to note that, unlike markdown, gemtext only supports up to h3 (###).
=> /link/to/somewhere This is a link and this text acts as the anchor
We can also include a list:
* Item 1
* Item 2
=> /path/to/image This text is displayed to the user until they click it to view the image
```
This is a preformatted block of text
useful for talking about code
```
> This is a quote
That's about everything that's supported.
`gemtext` is line orientated, so links and images cannot be added in the middle of a paragraph. Instead, gemlogs tend to insert reference like blocks:
If you view the shop link[1] you'll see that the foo is a bar[2].
=> link/to/shop [1] The shop link
=> link/elsewhere [2] Definition of a bar
* * *
### Converting
I needed to be able to convert my content to gemtext.
I draft posts in markdown, so I considered writing a standalone script to convert directly from that to gemtext. However, although the similarities in the syntax were appealing, I use Nikola's Magic Links and so needed posts to pass through Nikola so that they could be expanded.
Instead, I created a Nikola command plugin (I'll submit it to the plugin directory once I'm done fiddling with it).
The plugin works like nikola's `build` command, but with a few changes:
* It outputs gemtext rather than HTML
* It doesn't write into the `output` directory
* It copies over any raw files that exist in `gemini_files`
* It can inject a header into the generated files
* It generates Gemini specific RSS and Atom feeds
I decided against having it write into `output/` for two reasons:
* The `.gmi` files that it generates don't exist in Nikola's HTML tree, so will get deleted whenever a tidy is run
* My origin server is firewalled away from the net, so I needed to `rsync` the output to some other server anyway
With the plugin written and installed, invocation is easy
nikola gemini \
-o capsule \
--header gemini_files/gemini_header.gmi \
--files gemini_files/ \
--feed-url gemini://gem.bentasker.co.uk/
I added this to the commit post-hook which I use to trigger build and deployment of my site.
* * *
### Serving The Capsule
Serving a Gemini capsule requires a gemini capable server.
I decided to deploy Agate with a `docker-compose` like this:
services:
gemini:
restart: always
image: ghcr.io/mbrubeck/agate:latest
container_name: gemini
command: --hostname gem.bentasker.co.uk --hostname projects-gem.bentasker.co.uk --lang en-GB --log-ip
ports:
- 1965:1965
volumes:
- ./files/gemini/docroots:/gmi
- ./files/gemini/certs:/certs
There's an important note here: Although I'm only currently serving one capsule, I passed two domain names in via `--hostname` arguments. This is because `agate` switches to a different directory structure when virtualhosts are active - without this, I'd have had to move everything around if I later wanted to add another capsule.
Gemini encourages a Trust On First Use (TOFU) approach to SSL certs, so `agate` automatically generates long-lived certs at start up.
Getting content into the capsule was then just a case of updating my post-commit hook to rsync the `capsule/` dir over:
rsync -a --delete capsule/ capsule-server:docroots/gem.bentasker.co.uk/
Note: the trailing slash on `capsule/` means that `rsync` will sync the contents of that dir to the destination, rather than the directory itself. It's an annoying unituitive feature of rsync.
* * *
### Viewing The Gemini Capsule
Actually _viewing_ the capsule required a Gemini capable browser.
`lagrange` is a graphic browser.
It's not in the Ubuntu repos, so I installed it with `snap` (yeuch):
sudo snap install lagrange-tsugu
Whereas `amfora` is a CLI browser and _is_ in the repos:
sudo apt install amfora
On my phone, I have Buran and lagrange mobile, both available via F-Droid.
* * *
### Building Analytics
I'm something of a metrics nerd, so I wanted to be able to collect information about the capsule's activity.
I already collect docker container metrics, so could see its resource demands, but wanted to be able to tie this back to activity.
Gemini not having client side scripting means that analytics need to be driven by server access logs (just like we used to do on the web!).
Agate's logs look like this:
[2026-11-13T21:47:28Z INFO agate] 172.18.0.4:1965 - "gemini://gem.bentasker.co.uk/posts/documentation/development-programming/generating-a-static-html-archive-of-forgejo-issues.gmi" 20 "text/gemini;lang=en-GB"
It's quite a limited set of information, but _more_ than enough for basic analytic needs.
I wrote a script to parse logs and submit metrics into InfluxDB.
I've a cronjob which (along with a little bit of config setting) does:
docker logs gemini 2>&1 | ./agate_log_stats.py
A few Flux queries later, I had a grafana dashboard to expose analytics:
* * *
### Known Gaps
There are a few shortcomings with my current design:
**Link relocation** : The gemtext converter relocates links to a reference block immediately after the paragraph which contains them. However, it reuses the anchor text, so the usefulness of those links very much depends on how I've anchored it (adding a link to "here" for example, isn't very useful)
**External Links** : Almost every link that I add to a post will be to a location on the WWW. Most gemini browsers can handle those (`lagrange` for example, launches the system browser when they're clicked). But, the reverse isn't true - so I can't _easily_ link to another gemini capsule because WWW/Tor/I2P clients won't be ale to follow it.
I don't have a good solution for this yet, but one option might be to link to a gemini-to-HTTP proxy and then have my gemtext plugin replace links to that with direct `gemini://` links.
**Limited Internal Navigation** : Although tags are listed at the top of the page, my gemini plugin doesn't currently do anything for tag/category pages which makes it quite difficult to find other similar posts. Generating them should be too big of an issue, but I do need to figure out how to link to them without spamming the top (or bottom) of pages with links.
* * *
### Conclusion
Gemini's lightweight hypertext format and protocol make it quick and easy to serve.
There's definitely still room for improvement in my converter (and, probably, the way that I write posts), but `www.bentasker.co.uk` content is now available on the smallnet.
I've also got basic analytics, allowing me to see that the server's working and to draw out trends over time.
I should _probably_ have got around to this sooner: it turned out to be far easier than I was expecting.