Navigate

Earthstar

Start a webshare

Earthstar shares are private universes of data accessible only to those who know the address.

Earthstar replica servers are always online and publicly reachable via URL.

In this tutorial, we're going to combine these two things so that you and your friends can privately collaborate on a wiki, website, or image gallery while publicly exposing it to the web.

It's kind of like a website. It's kind of like a bucket of files. Let's call it a webshare.

To follow this tutorial, you'll need to be able to run commands in a console.

Table of contents

Generate an identity

To start using Earthstar, we need an identity. Let's generate a new one using the Earthstar CLI.

Installing the CLI requires an installation of Deno. You can find instruction on how to install Deno here.

Once Deno has been installed, paste, copy, and run the following command in your console (double click to highlight the whole thing):

deno install --allow-read --allow-write --allow-net --allow-run --allow-env --no-check --unstable -f --location https://earthstar-project.org -n earthstar https://deno.land/x/earthstar_cli/src/main.ts

Once you have the CLI installed, run the following command in your console:

earthstar identities generate <name> --current

Where <name> is a four-character nickname made of lowercase letters or numbers. This will be the permanent shortname of your new identity.

Don't worry about the shortname being permanent. It's meant as a way to let you and others more easily know which keypair you're interacting with. The important bits of online identity — display names, avatars, bios — can be changed as many times as you want.

Think of this identity as a stamp you use on documents to assert that they were really written by you.

Start a new share

We're going to curate data within a whole new self-contained universe, a share. Let's create one now.

earthstar shares generate <name>

Where name is something like bookclub or gamereviews or localevents. You'll get an address that looks like this:

+localevents.b9a8qcl1bb6r

This is your share. Let's write something in it.

Write your first post

The nicest way to write stuff is the way you like best. We're going to use the tools you already know to write data to the share you just made.

First, make a new directory where your share data will be held. You can do this with your filesystem UI, or in the console. You can call it whatever:

mkdir localevents

Inside your new folder, create a new text file. It can be a .txt file, a .md file, whatever you're comfortable with. Write something in it using your favourite editor. Here's my file next-sunday.md:

We'll be riding our bikes up and down from the harbour for charity next weekend. **Big lunch after**.

Great. Now let's get that into our share. Navigate to that directory in your console with cd:

cd localevents

and run earthstar shares sync-files:

? Choose a share › +localevents.b9a8qcl1bb6r
Synced +bananas with /Users/gwil/localevents

Your files are now synced into the share. Let's sync them to a replica server, and out into the world!

Deploy your own replica server

In this step we're going to deploy a replica server you and others will be able to sync with, and which will expose your curated data to the world.

Remix on Glitch

You'll have a URL like https://slimy-funny-door.glitch.me/earthstar-api/v2. Let's add it to our list of servers we like to sync with:

earthstar servers add https://slimy-funny-door.glitch.me/earthstar-api/v2

And then sync!

earthstar shares sync

Once the sync has completed, you should be able to browse to an address like https://slimy-funny-door.glitch.me/next-sunday.md (use the name of the file you wrote earlier), and see its contents displayed in your browser!

Work together!

Now that you've done the work of deploying the replica servers, you can bring others on board! Get them to:

And then start editing away! They'll sync their edits back to your replica server, ready for the world to see. The replica server you deployed is able to serve text, markdown, HTML, images, and a few different media types. So it only takes a little imagination to turn it into a full-blown wiki.