readme

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..f1d5978
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# urlbot (v3)
+
+## Purpose
+
+Resolving URLs... well, at least it started this way.
+
+This is a rewrite of the `urlbot-native`, an xmpp bot based on sleekxmpp to serve and entertain one or more jabber chat rooms. Its primary function is to resolve urls posted in the MUC and print the title, hence the name. Other than that, it has several useful functions like an answerphone (`record username message`) and several less useful, but funny commands (`cake`).
+
+## Install
+
+For automated installation, an ansible role has been written and can be found in deployment folder, along with some basic instructions. It's missing the rabbitmq setup, though - you'll have to do that manually in any case.
+
+## For manual installation
+
+install the python package (preferrably in a virtualenv), a rabbitmq server and place/edit configuration file "local_config.ini" as needed (see Configuration below). Run urlbotd-chat and urlbotd-worker with the daemon system of your choice. Unit files for systemd are provided with the deployment.
+
+### Python package
+
+Just copy-pasting parts of the ansible role here... and for being minimal, using only one virtualenv. That's up to you, the ansible role separates them.
+
+```bash
+# create virtualenv, load it
+$ python3 -m venv botenv && . botenv/bin/activate
+(botenv) $ pip install .[chatbot] .[worker]
+```
+
+### RabbitMQ
+
+```bash
+# (as root)
+% apt install rabbitmq-server
+% rabbitmq-plugins enable rabbitmq_management
+% rabbitmqctl adduser someusername somepassword
+% rabbitmqctl set_permissions -p / someusername ".*" ".*" ".*"
+```
+
+Feel free to refine the permissions if the rabbitmq server serves more than the urlbot's purpose.
+
+### Running
+
+As recommended, use the systemd unit files - the ansible role will deploy them in user space. You can copy them from the ansible role manually or create your own , if you have a preference. Or do whatever starts urlbotd-chat and urlbotd-worker from `$virtualenv_path/bin/`.
+
+### Configuration
+
+Keys currently to be set are described in `deploy/README` (adapt to key=value format for editing the ini file directly). Very minimal required values are jid/password, bot_nickname, amqp_uri and rooms in the local_config.ini.
+
+## Usage
+
+As soon as the bot has entered the chatroom, it will react on messages which fit the plugins incoming filter, mostly being approached with its configured nickname, but also on various trigger words. Use "botname: help" to get an overview of enabled commands and "botname: help dice" to get help for a certain command.
+
+## Administration
+
+urlbot will store runtime settings in a file named "persistent_config.ini", depending on what plugins are enabled. This is a not completely standardized version of ini format, which allows nested sections. You'll get it when you see it. Also, some plugins still read settings from there which should be in the local_settings.ini (or not, thus it's not resolved). You can stop the bot, edit the file and start it again - editing the file while the bot is running might work or go completely wrong.
+
+Other than that, I recommend to get comfy with rabbitmq for debugging messages if required.
+
+#### Purpose of the two daemons
+
+urlbotd-chat is communicating with the jabber server and forwards all messages to the amqp server and back (in an asynchronous fashion).
+
+urlbotd-worker does the heavy lifting, processing incoming messages with the plugin system. The plugin system heavily relies on the amqp features of assigning messages with a pattern, and each plugin is listening to the respective topics with its own thread.
+
+## Development
+
+Pull requests welcome, contact me in debianforum.de@chat.debianforum.de.
+
+The easiest (and probably most common) thing to achieve is to add another plugin - for a start, look for the "Dice" class and its references. You'll get the hang of it quickly.
+
+Further extensions (and there's a lot to be desired):
+
+* en-/disabling plugins programmatically
+
+* decide how plugin configuration should look like - centralised or not
+
+* decide whether ini is a good choice for configuration, and if runtime storage should use the same
+
+* rate limiting (hard nut, few moments where it's actually needed)
+
+* grep TODO in the repository...
+
+# License
+
+WTFPL (noone cares, if you sell this, you're a genius)
+
+