update comments

[erebus.git] / README.md

Modular Python3 IRC bot
===========================

Getting started
---------------
- `cp bot.config.example bot.config`
- `vim bot.config`
- Create a MySQL database, i.e. `CREATE DATABASE foo; GRANT ALL ON foo.* TO ...`
- `mysql <dump.sql`
- Add your auth (main NickServ nick/account name on other networks) in the database as owner: `INSERT INTO users VALUES ('YourAuth', 100);`
- `./run`

Install croncheck.sh in your crontab, if desired.  
`* * * * * /path/to/erebus/croncheck.sh`  
To suppress croncheck.sh from restarting the bot without removing from crontab, `touch dontstart`

Output will be placed in `logfile`, which is rotated to `oldlogs/`. (I strongly recommend `rm oldlogs/*` as a weekly crontab entry. `@weekly find /path/to/erebus/oldlogs/ -mtime +7 '!' -name .keep -delete`)

The bot targets Python 3 only. It has some time ago switched to being primarily tested on Python 3.
Python 2 support is presumed to have slowly eroded due to a lack of testing. It probably won't work.

Some modules require additional supporting materials, which can be found in `modules/contrib/`.


Module API
----------
The module API has largely remained backwards-compatible and likely will remain so into the future. However, it is still currently unstable, primarily because it's only tested with the included modules. If you find a change was introduced which breaks something you relied on, please raise a bug.

There is currently no documentation as to... well, anything. A good starter template for a new module is `modules/eval.py`. `modules/control.py` uses a significant subset of the API features available. `modules/foo.py` is intended as a demonstration module, and documents some of the major features.


Buffering
---------
The bot includes message buffering, with two different message queues (plus a "fast" message which sends immediately). This is to help prevent the bot from being flooded off the network by malicious users.

Unfortunately this does mean that the bot can be overwhelmed and take quite a while to respond. As an admin, you can use the `!QCLEAR` command to clear the queues. If you control the IRC server, you can exempt the bot from flooding checks and then set `[erebus] nofakelag = 1` in the bot.config. This will turn off message buffering completely.


Using the bot
-------------
Commands can be triggered by:
- Messaging the bot (`/msg Erebus whoami`)
- Prefixing the command with the bot's name and a colon (`/msg #channel Erebus: whoami`)
- Or prefixing the command with the trigger character set in bot.config (`/msg #channel !whoami` if `[erebus] trigger = !`)


Online Help
-----------
A command listing, with most (but not all) of the standard modules, is available at [https://jfr.im/help/](https://jfr.im/help/).

So long as you don't prohibit loading of the help module with `[autoloads] help = 0`, command info will be available with `!HELP <command>`

However, due to the message buffering mentioned above, there is no command listing available over IRC unless nofakelag is enabled. In order to generate a command listing, you must do the following:
1. Set `[help] path` in the config file, if needed, to a path which exists and is available on the web. f.e. `[help] path = /home/jrunyon/public_html/help/%(#)d.txt`. Several values are available, for use with !GENHELP; they are the same as the prefix characters @#+- (see !HELP GENHELP). This determines the path to which !GENHELP will save output files.
1. Set `[help] url` in the config file to a path where help can be found, f.e. `[help] url = https://jfr.im/help/%d.txt`. %d (or %s) will be replaced with the user's level. This determines the URL which is provided to users when they !SHOWCOMMANDS
1. Run `!GENHELP` whenever you change which modules (or commands) are available, or else just set `[help] autogen = 1`.

(With `nofakelag = 1`, `!SHOWCOMMANDS` will spam the user with the whole list of commands.)


Support
-------
If you have any questions, issues, fixes, etc. message DimeCadmium on irc.1459.io