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:
parent
ad6708d3f0
commit
d5dedda843
1 changed files with 81 additions and 0 deletions
81
src/docs/technical/ircbot.diviner
Normal file
81
src/docs/technical/ircbot.diviner
Normal 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.
|
Loading…
Reference in a new issue