An implementation of the Microsub server spec

Go to file

Peter Stuifzand ae55224d11 All checks were successful continuous-integration/drone/push Build is passing Details Create circular references between backend and hubbackend		2021-10-31 15:12:23 +01:00
.github	Update FUNDING.yml	2021-10-15 22:50:50 +02:00
cmd	Create circular references between backend and hubbackend	2021-10-31 15:12:23 +01:00
pkg	Fix foreign key errors for feed_id	2021-10-31 14:51:31 +01:00
templates	Add stream type postgres-stream	2021-05-11 17:23:25 +02:00
.drone.yml	Disable public Docker image, because we are in alpha mode	2021-10-31 01:38:17 +02:00
.gitignore	Add stream type postgres-stream	2021-05-11 17:23:25 +02:00
.pre-commit-config.yaml	Improve pre-commit-config.yml	2019-07-23 20:34:07 +02:00
docker-compose.yml	Use database backend instead of backend.json	2021-10-31 01:37:39 +02:00
Dockerfile	Compile execute inside Docker context	2019-08-07 00:29:03 +02:00
Dockerfile.alpine	Disable GOPATH -- use newer go images	2020-07-27 22:17:06 +02:00
Dockerfile.ek	Add version for Dockerfile.ek base image	2021-06-20 19:57:06 +02:00
go.mod	Fix foreign key errors for feed_id	2021-10-31 14:51:31 +01:00
go.sum	Use database backend instead of backend.json	2021-10-31 01:37:39 +02:00
LICENSE	Create LICENSE	2018-02-19 21:41:31 +01:00
README.md	Add explanation that you can use NAME instead of UID	2021-10-22 21:38:31 +02:00
TODO.md	Move templates to command	2021-05-30 21:56:25 +02:00

README.md

ekster

a Microsub server

Installing and running ekster

There are two methods for installing and running ekster.

Method 1: From binaries

Download the binaries from the latest release on Github.

Method 2: Install ekster from source with Go

ekster is build using go. To be able to install ekster you need a Go environment. Use these commands to install the programs.

go get -u p83.nl/go/ekster/cmd/eksterd
go get -u p83.nl/go/ekster/cmd/ek

eksterd uses Redis as the database to temporarily save the items and feeds. The more permanent information is saved in backend.json.

Running eksterd

Run both Redis and eksterd.

Generate the configuration file "backend.json". Run this command only once, as it will regenerate the configuration from scratch. See Configuration below for how to set up the json file.

eksterd new

Start redis

redis --port 6379

Start eksterd and pass the redis and port arguments.

EKSTER_TEMPLATES=$GOPATH/src/p83.nl/go/ekster/templates EKSTER_BASEURL=https://example.com eksterd -redis localhost:6379 -port 8090

You can now access eksterd on port 8090. To really use it, you should proxy eksterd behind a HTTP reverse proxy on port 80, or 443.

Method 3: Using Docker / Docker Compose

It's now also possible to use docker-compose to start an ekster server. Create an empty directory. Download docker-compose.yml from Github and run the following commands in that directory.

docker-compose pull
docker-compose run web new
# edit the backend.json file according to the instructions
docker-compose up

This will first pull the Docker image from the Docker hub. Then run the image to generate a default backend.json file. After editing, you can run docker-compose up to start the server. This will start Redis and ekster in such a way so that you can run the program without problems. By default it will choose a random port, to run the server. To make it really useful, you need to run this on an internet connected server and choose a fixed port.

The nicest way to run this docker-compose environment is with a proxy in the front. You can run ekster behind nginx-proxy.

When ekster is running

Add a link in the <head> tag to let the microsub client know where to find your server.

<link rel="microsub" href="https://microsub.example.com/microsub">

The domain name microsub.example.com needs to be replaced with the vhost that you use to proxy the server.

The microsub server responds to the /microsub url with the micropub protocol. You can use ek to talk to the endpoint.

It's also possible to visit the microsub server with your browser, there are a few ways to change settings.

Commands

`eksterd`

The command eksterd is the main server program. It will run a Microsub server. eksterd also needs a Redis server. It's used to temporarily remember the items.

The first time you should call the command

eksterd new

This will generate a configuration file backend.json where it remembers the feeds.

`ek`

The command ek is the command line client for Microsub server. It is able to call the different functions of the Microsub server. It isn't needed to use eksterd, but it can be useful. It can also be used with other servers that implement Microsub.

ek connect <url>

Connect with ek to you microsub server. After that you can call ek to control your microsub server. It should even work with other servers that support microsub.

Ek is a tool for managing Microsub servers.

Usage:

    ek [global arguments] command [arguments]

Commands:

    connect URL                  login to Indieauth url

    channels                     list channels
    channels NAME                create channel with NAME
    channels UID NAME            update channel UID with NAME
    channels -delete UID         delete channel with UID

    timeline UID                 show posts for channel UID
    timeline UID -after AFTER    show posts for channel UID starting from AFTER
    timeline UID -before BEFORE  show posts for channel UID ending at BEFORE

    search QUERY                 search for feeds from QUERY

    preview URL                  show items from the feed at URL

    follow UID                   show follow list for channel uid
    follow UID URL               follow url on channel uid

    unfollow UID URL             unfollow url on channel uid

    export opml                  export feeds as opml
    import opml FILENAME         import opml feeds

    export json                  export feeds as json
    import json FILENAME         import json feeds

global arguments:

  -verbose
        show verbose logging

Instead of the UID you can also use the NAME of the channel in most functions.

Configuration: backend.json

The backend.json file contains all information about channels, feeds and authentication. When the server is not running you can make changes to this file to add or remove feeds. This is not the easiest way, but it's possible.

When generating this file for the first time. It will contain a default configuration. This can be changed (and perhaps should be changed). The two parts that should be changed are:

"Me": "...",
"TokenEndpoint": "...",

The Me value should be set to the URL you use to sign into Monocle, or Micropub client.

TokenEndpoint should be the token_endpoint you use for that domain, ekster will check every 10 minutes, if the token is still valid. This could be retrieved automatically, but this doesn't happen at the moment.

Support me

Other Microsub projects

https://indieweb.org/Microsub
Aperture: code, hosted