|
1 | | -Mirror an IRCchannel in Zulip! |
| 1 | +#Zulip IRCIntegration |
2 | 2 |
|
3 | | -###Install the bridge software |
| 3 | +Mirror messages between an IRC channel and a Zulip channel in real-time! |
4 | 4 |
|
5 | | -1. Clone the Zulip API repository, and install its dependencies. |
| 5 | +{start_tabs} |
6 | 6 |
|
7 | | -``` |
8 | | - git clone https://github.com/zulip/python-zulip-api.git |
9 | | - cd python-zulip-api |
10 | | - python3 ./tools/provision |
11 | | - ``` |
| 7 | +1. {!download-python-bindings.md!} |
| 8 | + |
| 9 | +1. {!install-requirements.md!} |
| 10 | + |
| 11 | +1. Register a nick that ends with the suffix`_zulip` on your IRC server. |
12 | 12 |
|
13 | | - This will create a new Python virtualenv. You'll run the bridge service |
14 | | - inside this virtualenv. |
| 13 | +1. {!create-a-generic-bot.md!} |
15 | 14 |
|
16 | | -1. Activate the virtualenv by running the `source` command printed |
17 | | - at the end of the output of the previous step. |
| 15 | +1. Download the`zuliprc` configuration file of your bot by clicking the |
| 16 | + download (<iclass="fa fa-download"></i>) icon under the bot's name, and |
| 17 | + save to`~/.zuliprc`. |
18 | 18 |
|
19 | | -1. Go to the directory containing the bridge script if you haven't already done so |
| 19 | +1.[Subscribe the bot][subscribe-channels] to the Zulip channel where IRC |
| 20 | + messages should be mirrored. |
| 21 | + |
| 22 | +1. Begin mirroring messages between the IRC channel and the Zulip channel |
| 23 | + by running the`irc-mirror.py` script with the |
| 24 | +[required command-line arguments](#required-arguments). Use the |
| 25 | +[optional arguments](#optional-arguments) to configure the mirroring |
| 26 | + behavior. |
| 27 | + |
| 28 | + Here's an example command that mirrors messages between the |
| 29 | +**#python-mypy** channel on the`irc.freenode.net` server and the "mypy" |
| 30 | + topic on the**#irc-discussions** channel on Zulip: |
20 | 31 |
|
21 | 32 | ``` |
22 | | - cd zulip/integrations/bridge_with_irc |
| 33 | + python {{ integration_path }}/irc-mirror.py \ |
| 34 | + --irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \ |
| 35 | + --stream='irc-discussions' --topic='mypy' |
23 | 36 | ``` |
24 | 37 |
|
25 | | -1. Install the bridge dependencies in your virtualenv, by running: |
| 38 | +1. Messages will be mirrored only when the terminal session with the bot |
| 39 | + remains open. Consider using `screen` to run the bot in the background. |
| 40 | + You can restart the integration at any time by re-running the |
| 41 | + `irc-mirror.py` script. |
| 42 | +
|
| 43 | +{end_tabs} |
| 44 | +
|
| 45 | +You're done! Messages in your Zulip channel may look like: |
26 | 46 |
|
27 | | - ``` |
28 | | - pip install -r requirements.txt |
29 | | - ``` |
| 47 | + |
30 | 48 |
|
31 | | -### Configure the bridge |
| 49 | +Messages in your IRC channel may look like: |
32 | 50 |
|
33 | | -1. {!create-a-generic-bot.md!} |
34 | | - Download the bot's `zuliprc` configuration file to your computer. |
| 51 | + |
35 | 52 |
|
36 | | -1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip |
37 | | - stream that will contain the mirror. |
| 53 | +[subscribe-channels]: /help/manage-user-channel-subscriptions#subscribe-a-user-to-a-channel |
38 | 54 |
|
39 | | -1. Inside the virtualenv you created above, run: |
| 55 | +### Configuration options |
40 | 56 |
|
41 | | - ``` |
42 | | - python irc-mirror.py --irc-server=IRC_SERVER --channel=<CHANNEL> --nick-prefix=<NICK> \ |
43 | | - --stream=<STREAM> [--topic=<TOPIC>] \ |
44 | | - --site=<zulip.site> --user=<bot-email> \ |
45 | | - --api-key=<api-key> |
46 | | - ``` |
| 57 | +The integration script accepts the following command-line arguments: |
47 | 58 |
|
48 | | - `--topic` is a Zulip topic, is optionally specified, defaults to "IRC". |
| 59 | +#### Required arguments |
49 | 60 |
|
50 | | -Example command: |
| 61 | +- `--irc-server`: The IRC server to mirror. |
51 | 62 |
|
52 | | -``` |
53 | | -./irc-mirror.py --irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror\ |
54 | | ---stream='test here' --topic='#mypy'\ |
55 | | ---site="https://chat.zulip.org" --user=bot@email.com\ |
56 | | ---api-key=DeaDbEEf |
57 | | -``` |
| 63 | +- `--nick-prefix`: Your registered IRC nick without the `_zulip` suffix. |
58 | 64 |
|
59 | | -**Congratulations! You're done!** |
| 65 | +- `--channel`: The IRC channel to mirror. |
60 | 66 |
|
61 | | -Your Zulip messages may look like: |
| 67 | +- `--stream`: The name of the Zulip channel you want to mirror. The default |
| 68 | + channel name is **#general**. |
62 | 69 |
|
63 | | - |
| 70 | +#### Optional arguments |
64 | 71 |
|
65 | | -Your IRC messages may look like: |
| 72 | +- `--topic`: The name of the Zulip topic you want to receive and send |
| 73 | + messages in. The default topic name is "IRC". |
66 | 74 |
|
67 | | - |
| 75 | +- `--port`: The port to connect to the IRC server on. Defaults to 6667. |
| 76 | +
|
| 77 | +- `--nickserv-pw`: Password corresponding to the IRC nick. |
| 78 | +
|
| 79 | +- `--sasl-password`: Password for SASL authentication. |