1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-10 08:52:39 +01:00

Document the IRC bot

Summary: Write a little documentation about how to get the IRC bot running since
there's a reasonable process with some examples but no documentation.

Test Plan: Generated, read the documentation.

Reviewers: btrahan, jungejason

Reviewed By: jungejason

CC: iAladdin, aran, jungejason

Maniphest Tasks: T686

Differential Revision: 1244
This commit is contained in:
epriestley 2011-12-20 09:32:05 -08:00
parent ad6708d3f0
commit d5dedda843

View file

@ -0,0 +1,81 @@
@title IRCBot Technical Documentation
@group irc
Configuring and extending the IRCBot.
= Overview =
Phabricator includes a simple IRC bot daemon, which is primarily intended as
an example of how you can write an external script that interfaces with
Phabricator over Conduit and does some kind of useful work. If you use IRC, you
can also have the bot hang out in your channel.
NOTE: The IRC bot is somewhat experimental and not very mature.
= Configuring the Bot =
The bot reads a JSON configuration file. You can find an example in:
resources/ircbot/example_config.json
These are the configuration values it reads:
- ##server## String, required, the server to connect to.
- ##port## Int, optional, the port to connect to (defaults to 6667).
- ##ssl## Bool, optional, whether to connect via SSL or not (defaults to
false).
- ##nick## String, nickname to use.
- ##user## String, optional, username to use (defaults to ##nick##).
- ##pass## String, optional, password for server.
- ##nickpass## String, optional, password for NickServ.
- ##join## Array, list of channels to join.
- ##handlers## Array, list of handlers to run. These are like plugins for the
IRCBot.
- ##conduit.uri##, ##conduit.user##, ##conduit.cert## Conduit configuration,
see below.
= Handlers =
You specify a list of "handlers", which are basically plugins or modules for
the IRC bot. These are the default handlers available:
- @{class:PhabricatorIRCProtocolHandler} This handler implements the raw IRC
protocol (e.g., responding with PONG when the server sends PING). You should
probably leave it in the handler list unless you implement the protocol
details yourself in another handler.
- @{class:PhabricatorIRCObjectNameHandler} This handler looks for users
mentioning Phabricator objects like "T123" and "D345" in chat, looks them
up, and says their name with a link to the object. Requires conduit.
You can also write your own handlers, by extending
@{class:PhabricatorIRCHandler}.
= Conduit =
Some handlers (e.g., @{class:PhabricatorIRCObjectNameHandler}) need to read data
from Phabricator. They do this over Conduit, Phabricator's HTTP API. You can
use this method to allow other scripts or programs to access Phabricator's data
from different servers and in different languages.
To allow the bot to access Conduit, you need to create a user that it can login
with. To do this, login to Phabricator as an administrator and go to
##People -> Create New Account##. Create a new account and flag them as a
"System Agent". Then in your configuration file, set these parameters:
- ##conduit.uri## The URI for your Phabricator install, like
##http://phabricator.example.com/##
- ##conduit.user## The username your bot should login to Phabricator with --
whatever you selected above, like ##phabot##.
- ##conduit.cert## The user's certificate, from the "Conduit Certificate" tab
in the user's administrative view.
Now the bot should be able to connect to Phabricator via Conduit.
= Starting the Bot =
The bot is a Phabricator daemon, so start it with ##phd##:
./bin/phd launch ircbot <absolute_path_to_config_file>
If you have issues you can try ##debug## instead of ##launch##, see
@{article:Managing Daemons with phd} for more information.