Browsing and publishing Gemini on a... Kobo?!

published: 2021-01-07

I have a Kobo Libra H2O. It's a little e-ink tablet-like device. While the specs aren't great, it does run Linux, which means theoretically one can run whatever programs they want on it! ...As long as those programs are line-based command-line or written for Kobo's special flavor of Qt.

Getting shell access to your Kobo

The first step is getting KOReader on the Kobo. Not only is it a much better reading app than the Kobo's built-in Nickel, it also includes a terminal emulator, a text editor, and a SSH server. The install instructions are on the KOReader wiki. I personally recommend using the NickelMenu installation method halfway down the page.

After you have KOReader set up, plug your Kobo into a computer with a USB cable.

cd /path/to/your/kobo/

cd ./.adds/koreader/settings/SSH/

ssh-keygen -trsa -b 2048 -f ~/.ssh/kobo

cp ~/.ssh/kobo.pub ./authorized_keys

Safely disconnect your Kobo from your computer. Go into KOReader, then tap the gear icon on the top of the screen. Tap "Network". Connect to the same WiFi network your computer is on, then tap on "SSH server" and then "Start SSH server".

Shell access should only be necessary for troubleshooting. For this guide, we are more interested in SFTP file transfer.

Setting up your environment

There are four programs you'll need:

1. godown: an HTML to Markdown converter
2. gemget: wget, but for the Gemini protocol
3. kurly: cURL, but written in Golang (since the version of wget that ships with KOReader's Dropbear doesn't support HTTPS for some reason)
4. dave: a simple WebDAV server

The first three we will install on your Kobo. The last one will go on the server that runs your Gemini site.

I specifically picked programs written in Golang because they compile to a single binary. This means no trying to manually resolve dependencies, since the Kobo doesn't have a package manager installed (that I could see). However, they still must be compiled for ARM. I compiled them on my Raspberry Pi 4 (which is also an ARM device) and copied the resulting binaries to my computer. If you want to cross-compile on your local computer instead, you're on your own.

The config file for dave needs to go in ~/.swd/config.yaml on the remote server. It should look something like this:

address: "domain.tld"    # the bind address
port: "7778"            # the listening port
dir: "/path/to/your/gemsite/files"     # the provided base dir
prefix: "/"       # the url-prefix of the original url
users:
#  user:                 # with password 'foo' and jailed access to '/home/webdav/user'
#    password: "HASHED_PASSWORD"
#    subdir: "/user"
  YOURUSERNAME:                # with password 'foo' and access to '/home/webdav'
    password: "HASHED_PASSWORD"
tls:
  keyFile: gemini.key
  certFile: gemini.crt