Getting started

A site in a box

Instead of a static host, a site can run as one small program. Visitors get the published pages. People who sign in at /edit get the editor, at the same address, from any browser.

This is the way to give a site to someone who will never open a terminal. You host it once. After that they go to their own site, add /edit, sign in, and click on the words.

Start it

npm start

That runs verso serve. The site is on port 8080, or whatever PORT says. The first time, the log ends with a link:

Nobody can edit yet. To become the first owner, open:

  http://localhost:8080/edit/join?t=…

Open it with the site's real address in place of localhost, choose a password, and you're the site's owner, looking at the editor. Invite everyone else from People in the bar.

What visitors see, and when

Visitors get the published pages, built ahead of time and served as files. Edits save as you type, and other people who are signed in see them, but visitors don't until someone presses Publish. Then the pages are rebuilt and live in about a second. Unpublished work stays private through a restart.

Every Publish is a restore point, under the name of the person who pressed it, so History shows who published what.

Where to run it

Anywhere that runs a program and keeps a disk: a small server of your own, or a host that builds from a Dockerfile. Two things matter.

  • A disk that's kept. The edits, the history and the list of people are files in the site's folder. Some hosts give a program a fresh disk on every restart, which would lose them. Give the site a disk that lasts and tell Verso where it is with VERSO_DATA; the site moves onto it the first time and runs from there. Each start, the log says how many starts the files have been kept through.
  • HTTPS. Put the site behind your host's HTTPS, as you would any site people sign in to.

A new site comes with a Dockerfile that does both:

docker build -t my-site .
docker run -p 8080:8080 -v my-site-data:/data my-site

Keeping a second copy

The history lives in the box, and that's enough for the site to work. If the folder has a git remote, every Publish is also pushed there, so there's a copy somewhere else. People sees which it is at the bottom of its panel. Changes pushed to that repository from outside, like a template you changed on your own computer, arrive the next time the site starts or someone publishes.

Moving between a box and a static host

It's the same folder either way. npm run build still makes dist/ for any static host, and a site that has been on a static host can be served as a box by running npm start in it.

If you're locked out

In the site's folder on the server, run:

npx verso owner

It writes a link that makes one new owner. Only someone who can already run commands on the server can do this.