README.md

   1 # viera
   2
   3 A useful IRC and ActivityPub bot which links identities and relays messages.
   4
   5
   6 ## Copyleft
   7
   8 `viera` is copyrighted, but free software, licensed under the terms of the GNU Affero
   9 General Public License version 3 (AGPLv3) license.  You can find a copy of it in this
  10 package as the `LICENSE` file.
  11
  12
  13 ## Setup
  14
  15 `viera` uses the new `pipenv` python environment manager, you should install it before
  16 trying to make use of this software:
  17
  18     $ pip3 install pipenv
  19
  20 Next, create the virtual environment for `viera` to use:
  21
  22     $ pipenv install
  23
  24 Next, copy `viera.yaml.example` to `viera.yaml` and edit it as appropriate:
  25
  26     $ cp viera.yaml.example viera.yaml
  27     $ $EDITOR viera.yaml
  28
  29 Finally, you can launch viera:
  30
  31     $ pipenv run python3 -m viera
  32
  33 It is suggested to run this under some sort of supervisor, such as runit, daemontools,
  34 s6 or systemd.  Configuration of the supervisor is not covered here, as it is different
  35 depending on which system you have available.
  36
  37 The bot runs a webserver, internally, on localhost at port 8080.  This needs to be
  38 forwarded by nginx or similar.  The webserver is used to receive ActivityPub messages,
  39 and needs to be secured with an SSL certificate inside nginx or similar.  Configuration
  40 of your webserver is not discussed here, but any guide explaining how to configure a
  41 modern non-PHP web application should cover it.
  42
  43
  44 ## Getting started
  45
  46 It is required to register a services account for the bot.  This is different depending
  47 on the IRC network in use.
  48
  49 It is also required to use SASL to authenticate to the IRC network.  This is supported on
  50 most IRC networks.
  51
  52 `viera` works with ActivityPub identities as the primary source of trust.  This means that
  53 you are required to link an ActivityPub identity to your IRC identity in order to
  54 authenticate to the bot.  To do that, make sure you are logged into your NickServ or similar
  55 account and message the bot on IRC:
  56
  57     /msg yourbot auth
  58
  59 The bot will respond with an authentication token that you must supply via the fediverse,
  60 in most cases you can just copy and paste the exact message it provides.
  61
  62
  63 ### Following accounts to relay to IRC
  64
  65 Once you have authenticated to an AP identity which is listed in the `privileged` group in
  66 the config file, you may configure the bot to follow accounts, by using the `follow` command:
  67
  68     /msg yourbot follow https://pleroma.site/users/kaniini
  69
  70 This will cause your bot to request an ActivityPub connection between itself and the user you
  71 followed.  In most cases this will be set up immediately, but in some cases, there may be a delay,
  72 such as when accounts are restricted.
  73
  74 If you want the bot to stop following an account, you can use the `unfollow` command:
  75
  76     /msg yourbot unfollow https://pleroma.site/users/kaniini
  77