2018-05-16 15:24:26 +00:00
|
|
|
# ekster
|
|
|
|
|
|
|
|
|
|
a microsub server
|
2018-02-19 20:39:22 +00:00
|
|
|
|
|
|
|
|
|
2018-05-16 15:40:57 +00:00
|
|
|
## Warning!
|
|
|
|
|
|
2018-02-19 20:39:22 +00:00
|
|
|
Very alpha: no warranty.
|
2018-05-16 15:40:57 +00:00
|
|
|
|
2018-05-23 19:13:28 +00:00
|
|
|
## Installing and running ekster
|
|
|
|
|
|
2018-09-11 18:50:58 +00:00
|
|
|
There are two methods for installing and running ekster.
|
|
|
|
|
|
2018-05-23 19:13:28 +00:00
|
|
|
### Method 1: Install ekster (from source)
|
2018-05-16 15:40:57 +00:00
|
|
|
|
|
|
|
|
ekster is build using [go](https://golang.org). To be able to install ekster
|
|
|
|
|
you need a Go environment. Use these commands to install the programs.
|
|
|
|
|
|
2018-07-28 15:52:59 +00:00
|
|
|
go get -u p83.nl/go/ekster/cmd/eksterd
|
|
|
|
|
go get -u p83.nl/go/ekster/cmd/ek
|
2018-05-16 15:40:57 +00:00
|
|
|
|
2018-05-23 19:13:28 +00:00
|
|
|
`eksterd` uses [Redis](https://redis.io/) 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
|
2018-09-11 18:50:58 +00:00
|
|
|
it will regenerate the configuration from scratch. See **Configuration** below for
|
2018-05-23 19:13:28 +00:00
|
|
|
how to set up the json file.
|
|
|
|
|
|
|
|
|
|
eksterd new
|
|
|
|
|
|
|
|
|
|
Start redis
|
|
|
|
|
|
|
|
|
|
redis --port 6379
|
|
|
|
|
|
|
|
|
|
Start eksterd and pass the redis and port arguments.
|
|
|
|
|
|
2018-09-11 18:50:58 +00:00
|
|
|
EKSTER_TEMPLATES=$GOPATH/src/p83.nl/go/ekster/templates EKSTER_BASEURL=https://example.com eksterd -redis localhost:6379 -port 8090
|
2018-05-23 19:13:28 +00:00
|
|
|
|
|
|
|
|
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 2: Using Docker / Docker Compose
|
|
|
|
|
|
2018-09-11 18:50:58 +00:00
|
|
|
It's now also possible to use docker-compose to start an ekster server. Create an empty directory.
|
|
|
|
|
Download [docker-compose.yml](https://raw.githubusercontent.com/pstuifzand/ekster/master/docker-compose.yml) from Github
|
|
|
|
|
and run the following commands in that directory.
|
|
|
|
|
|
2018-05-23 19:13:28 +00:00
|
|
|
docker-compose pull
|
|
|
|
|
docker-compose run web new
|
2018-09-11 18:50:58 +00:00
|
|
|
# edit the backend.json file according to the instructions
|
2018-05-23 19:13:28 +00:00
|
|
|
docker-compose up
|
|
|
|
|
|
2018-09-11 18:50:58 +00:00
|
|
|
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](https://github.com/jwilder/nginx-proxy).
|
|
|
|
|
|
2018-05-23 19:13:28 +00:00
|
|
|
## When ekster is running
|
|
|
|
|
|
|
|
|
|
Add a link in the `<head>` tag to let the microsub client know where to find your server.
|
|
|
|
|
|
2018-09-11 18:50:58 +00:00
|
|
|
<link rel="microsub" href="https://microsub.example.com/microsub">
|
2018-05-23 19:13:28 +00:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2018-09-11 18:50:58 +00:00
|
|
|
It's also possible to visit the microsub server with your browser, there are a few ways to
|
|
|
|
|
change settings.
|
|
|
|
|
|
2018-05-23 19:13:28 +00:00
|
|
|
## Commands
|
|
|
|
|
|
2018-05-16 15:40:57 +00:00
|
|
|
### `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
|
|
|
|
|
|
2018-05-16 15:45:06 +00:00
|
|
|
This will generate a configuration file `backend.json` where it remembers the feeds.
|
2018-05-16 15:40:57 +00:00
|
|
|
|
|
|
|
|
### `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.
|
|
|
|
|
|
2018-05-23 16:13:22 +00:00
|
|
|
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.
|
|
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
Ek is a tool for managing Microsub servers.
|
|
|
|
|
|
|
|
|
|
Usage:
|
|
|
|
|
|
|
|
|
|
ek [global arguments] command [arguments]
|
2018-05-23 16:13:22 +00:00
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
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
|
2018-05-23 16:13:22 +00:00
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
follow UID show follow list for channel uid
|
|
|
|
|
follow UID URL follow url on channel uid
|
2018-05-23 16:13:22 +00:00
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
unfollow UID URL unfollow url on channel uid
|
2018-05-23 16:13:22 +00:00
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
export opml export feeds as opml
|
|
|
|
|
import opml FILENAME import opml feeds
|
2018-05-23 16:13:22 +00:00
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
export json export feeds as json
|
|
|
|
|
import json FILENAME import json feeds
|
2018-05-23 16:13:22 +00:00
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
global arguments:
|
2018-05-23 16:13:22 +00:00
|
|
|
|
2018-09-11 18:35:50 +00:00
|
|
|
-verbose
|
|
|
|
|
show verbose logging
|
2018-05-23 16:13:22 +00:00
|
|
|
|
2018-05-23 19:13:28 +00:00
|
|
|
## Configuration: backend.json
|
2018-05-16 19:45:19 +00:00
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
2018-09-11 18:50:58 +00:00
|
|
|
"Me": "...",
|
|
|
|
|
"TokenEndpoint": "...",
|
2018-05-16 19:45:19 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
