From 0405b0463bcb344dd9f32f9a97d607933f696374 Mon Sep 17 00:00:00 2001 From: William Pitcock Date: Sat, 18 Aug 2018 00:05:48 -0500 Subject: [PATCH] expand README --- README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 75 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9e9d180..44acb68 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,77 @@ # viera -An IRC and ActivityPub bot which links identities. \ No newline at end of file +A useful IRC and ActivityPub bot which links identities and relays messages. + + +## Copyleft + +`viera` 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. + + +## Setup + +`viera` uses the new `pipenv` python environment manager, you should install it before +trying to make use of this software: + + $ pip3 install pipenv + +Next, create the virtual environment for `viera` to use: + + $ pipenv install + +Next, copy `viera.yaml.example` to `viera.yaml` and edit it as appropriate: + + $ cp viera.yaml.example viera.yaml + $ $EDITOR viera.yaml + +Finally, you can launch viera: + + $ pipenv run python3 -m viera + +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. + + +## Getting started + +It is required to register a services account for the bot. This is different depending +on the IRC network in use. + +It is also required to use SASL to authenticate to the IRC network. This is supported on +most IRC networks. + +`viera` works with ActivityPub identities as the primary source of trust. This means that +you are required to link an ActivityPub identity to your IRC identity in order to +authenticate to the bot. To do that, make sure you are logged into your NickServ or similar +account and message the bot on IRC: + + /msg yourbot auth + +The bot will respond with an authentication token that you must supply via the fediverse, +in most cases you can just copy and paste the exact message it provides. + + +### Following accounts to relay to IRC + +Once you have authenticated to an AP identity which is listed in the `privileged` group in +the config file, you may configure the bot to follow accounts, by using the `follow` command: + + /msg yourbot follow https://pleroma.site/users/kaniini + +This will cause your bot to request an ActivityPub connection between itself and the user you +followed. In most cases this will be set up immediately, but in some cases, there may be a delay, +such as when accounts are restricted. + +If you want the bot to stop following an account, you can use the `unfollow` command: + + /msg yourbot unfollow https://pleroma.site/users/kaniini +