README.md

   1 # ActivityRelay
   2
   3 A generic LitePub message relay.
   4
   5
   6 ## Copyleft
   7
   8 ActivityRelay is copyrighted, but free software, licensed under the terms of the GNU
   9 Affero General Public License version 3 (AGPLv3) license.  You can find a copy of it
  10 in this package as the `LICENSE` file.
  11
  12
  13 ## Setup
  14
  15 You need at least Python 3.5 (3.5.2 or newer recommended) to make use of this software.
  16 It simply will not run on older Python versions.
  17
  18 Install the dependencies as you normally would (`pip3 install -r requirements.txt`).
  19
  20 Copy `relay.yaml.example` to `relay.yaml` and edit it as appropriate:
  21
  22     $ cp relay.yaml.example relay.yaml
  23     $ $EDITOR relay.yaml
  24
  25 Finally, you can launch the relay:
  26
  27     $ python3 -m relay
  28
  29 It is suggested to run this under some sort of supervisor, such as runit, daemontools,
  30 s6 or systemd.  Configuration of the supervisor is not covered here, as it is different
  31 depending on which system you have available.
  32
  33 The bot runs a webserver, internally, on localhost at port 8080.  This needs to be
  34 forwarded by nginx or similar.  The webserver is used to receive ActivityPub messages,
  35 and needs to be secured with an SSL certificate inside nginx or similar.  Configuration
  36 of your webserver is not discussed here, but any guide explaining how to configure a
  37 modern non-PHP web application should cover it.
  38
  39
  40 ## Getting Started
  41
  42 Normally, you would direct your LitePub instance software to follow the LitePub actor
  43 found on the relay.  In Pleroma this would be something like:
  44
  45     $ MIX_ENV=prod mix relay_follow https://your.relay.hostname/actor
  46
  47 Mastodon uses an entirely different relay protocol but supports LitePub relay protocol
  48 as well when the Mastodon relay handshake is used.  In these cases, Mastodon relay
  49 clients should follow `http://your.relay.hostname/inbox` as they would with Mastodon's
  50 own relay software.
  51
  52
  53 ## Performance
  54
  55 Performance is very good, with all data being stored in memory and serialized to a
  56 JSON-LD object graph.  Worker coroutines are spawned in the background to distribute
  57 the messages in a scatter-gather pattern.  Performance is comparable to, if not
  58 superior to, the Mastodon relay software, with improved memory efficiency.
  59
  60
  61 ## Management
  62
  63 You can perform a few management tasks such as peering or depeering other relays by
  64 invoking the `relay.manage` module.
  65
  66 This will show the available management tasks:
  67
  68     $ python3 -m relay.manage
  69
  70 When following remote relays, you should use the `/actor` endpoint as you would in
  71 Pleroma and other LitePub-compliant software.
  72
  73 ## Docker
  74
  75 You can run ActivityRelay with docker. Edit `relay.yaml` so that the database
  76 location is set to `./data/relay.jsonld` and then build and run the docker
  77 image :
  78
  79     $ docker volume create activityrelay-data
  80     $ docker build -t activityrelay .
  81         $ docker run -d -p 8080:8080 -v activityrelay-data:/workdir/data activityrelay