From 0405b0463bcb344dd9f32f9a97d607933f696374 Mon Sep 17 00:00:00 2001
From: William Pitcock <nenolod@dereferenced.org>
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
+