Gwil's garden

as it was pre-2024.

Earthstar in April - CLI, Replica servers, webshares

April 28, 2022

A network of Earthstar peers

Okay, I've probably said this at least a hundred times, but: did you know this blog is powered by Earthstar?

  1. I write regular markdown files in a regular directory on my regular filesystem using my regular text editor.
  2. I transfer those files' contents into a local Earthstar replica.
  3. I sync that replica to this web server, which happens to be an Earthstar peer itself.
  4. And because my webserver understands Earthstar, it uses it like a database to serve up these blog posts.

If you can't tell, I really love this. It means I get to use my favourite tools to author this blog. It means all my stuff is where I want it: offline, on my computer. And you know what? If I got serious about this blogging thing, I could get an editor, sync my stuff over to them, and get them to sync their edits to the webserver. Hypothetically.

The pattern of "edit files on your computer and sync them to each other + web servers" can be used for so much more than just blogs:

These are all things you could build with Earthstar, but until today only a huge nerd like me could be bothered to hook all of it up. So I've made a bunch of new tools to help more modestly-sized nerds do the same thing:

These things are useful separately, but together they are a lot more fun.

Earthstar CLI

This is a complete client for everything Earthstar in your console:

... and an exciting new feature: filesystem sync. This bidirectionally synchronises the contents of an Earthstar replica with the contents of a filesystem directory, so you can use your filesystem and favourite apps to view and modify a share's contents. For example writing and editing a bunch of markdown files with some fancy knowledgebase tool.

Here's a new guide to installing and getting started with the Earthstar CLI..

But what good is having a share full of cool documents if you can't sync them anywhere?

Replica servers

In the last few months I think I've written about five different replica servers: one that could sync with classic Earthstar clients; one that could serve content via the web; one that could sync over HTTP instead of websockets, etc. etc. Again, only a huge nerd like me is going to be bothered to do that.

Replica servers should be easy to run, easy to deploy, and users should be able to customise according to their wishes. So I've built a new extensible replica server framework which runs on both Deno and Node.

It has extensions for:

That last extension, the one in bold, is the coolest one. Whenever someone sends a HTTP request to your replica server for, let's say, /sandwiches/the-best-one.md, it will check if there's a document with a corresponding path in an Earthstar replica and serve it up. If those documents have hyperlinks, or references to images in them, they will also work just fine. You can use this to build websites, wikis, knowledgebases, whatever. For now I'm calling this fusing of webserver and share a webshare.

I want to make it trivially easy for people to have their own replica servers like this, so I've made a few templates which you can deploy in a single click. Here's one for Glitch.

To learn more about replica servers, there's a new guide on the Earthstar website.

If you'd like a complete tutorial on starting your own webshare, from installing and using the CLI to deploying a server, you can find one here.

And if you'd like to dig into the new replica server API, there's documentation aplenty.

Thanks, and what's next

Firstly, a huge thank you to the testers who helped test the new CLI and whose help really made it shine. It's so much more fun to build software when you have great people helping you.

Secondly, with this milestone finished, what's being worked on next?

Earthstar has some tight restrictions around how much data you can store per document: four megabytes. It also doesn't have an efficient way to store binary data like images or music. Obviously applications need this stuff — we want Earthstar to be usable for music collections, private instagrams, and media archives. So removing these limitations is where I'm turning my attention to next. That file sync feature is going to become something else.

As always, thanks to NLnet foundation for funding this work.