README.md 2.8 KB
Newer Older
kaniini's avatar
kaniini committed
1
# ActivityRelay
kaniini's avatar
kaniini committed
2

kaniini's avatar
kaniini committed
3
A generic LitePub message relay.
kaniini's avatar
kaniini committed
4 5 6 7


## Copyleft

kaniini's avatar
kaniini committed
8 9 10
ActivityRelay is copyrighted, but free software, licensed under the terms of the GNU
Affero General Public License version 3 (AGPLv3) license.  You can find a copy of it
in this package as the `LICENSE` file.
kaniini's avatar
kaniini committed
11 12 13 14


## Setup

15 16 17
You need at least Python 3.5 (3.5.2 or newer recommended) to make use of this software.
It simply will not run on older Python versions.

kaniini's avatar
kaniini committed
18
Install the dependencies as you normally would (`pip3 install -r requirements.txt`).
kaniini's avatar
kaniini committed
19

kaniini's avatar
kaniini committed
20
Copy `relay.yaml.example` to `relay.yaml` and edit it as appropriate:
kaniini's avatar
kaniini committed
21

kaniini's avatar
kaniini committed
22 23
    $ cp relay.yaml.example relay.yaml
    $ $EDITOR relay.yaml
kaniini's avatar
kaniini committed
24

kaniini's avatar
kaniini committed
25
Finally, you can launch the relay:
kaniini's avatar
kaniini committed
26

kaniini's avatar
kaniini committed
27
    $ python3 -m relay
kaniini's avatar
kaniini committed
28 29 30 31 32 33 34 35 36 37 38 39

It is suggested to run this under some sort of supervisor, such as runit, daemontools,
s6 or systemd.  Configuration of the supervisor is not covered here, as it is different
depending on which system you have available.

The bot runs a webserver, internally, on localhost at port 8080.  This needs to be
forwarded by nginx or similar.  The webserver is used to receive ActivityPub messages,
and needs to be secured with an SSL certificate inside nginx or similar.  Configuration
of your webserver is not discussed here, but any guide explaining how to configure a
modern non-PHP web application should cover it.


kaniini's avatar
kaniini committed
40
## Getting Started
kaniini's avatar
kaniini committed
41

kaniini's avatar
kaniini committed
42 43
Normally, you would direct your LitePub instance software to follow the LitePub actor
found on the relay.  In Pleroma this would be something like:
kaniini's avatar
kaniini committed
44

kaniini's avatar
kaniini committed
45
    $ MIX_ENV=prod mix relay_follow https://your.relay.hostname/actor
kaniini's avatar
kaniini committed
46

kaniini's avatar
kaniini committed
47 48 49 50
Mastodon uses an entirely different relay protocol but supports LitePub relay protocol
as well when the Mastodon relay handshake is used.  In these cases, Mastodon relay
clients should follow `http://your.relay.hostname/inbox` as they would with Mastodon's
own relay software.
kaniini's avatar
kaniini committed
51 52


kaniini's avatar
kaniini committed
53
## Performance
kaniini's avatar
kaniini committed
54

kaniini's avatar
kaniini committed
55 56 57 58
Performance is very good, with all data being stored in memory and serialized to a
JSON-LD object graph.  Worker coroutines are spawned in the background to distribute
the messages in a scatter-gather pattern.  Performance is comparable to, if not
superior to, the Mastodon relay software, with improved memory efficiency.
59 60 61 62 63 64 65 66 67 68 69 70 71


## Management

You can perform a few management tasks such as peering or depeering other relays by
invoking the `relay.manage` module.

This will show the available management tasks:

    $ python3 -m relay.manage

When following remote relays, you should use the `/actor` endpoint as you would in
Pleroma and other LitePub-compliant software.
72 73 74 75 76 77 78 79 80 81

## Docker

You can run ActivityRelay with docker. Edit `relay.yaml` so that the database
location is set to `./data/relay.jsonld` and then build and run the docker
image :

    $ docker volume create activityrelay-data
    $ docker build -t activityrelay .
	$ docker run -d -p 8080:8080 -v activityrelay-data:/workdir/data activityrelay