-
-
Notifications
You must be signed in to change notification settings - Fork 392
Update the doc of the IRC bridge integration. #870
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,67 +1,79 @@ | ||
Mirror an IRC channel in Zulip! | ||
# Zulip IRC Integration | ||
|
||
### Install the bridge software | ||
Mirror messages between an IRC channel and a Zulip channel in real-time! | ||
|
||
1. Clone the Zulip API repository, and install its dependencies. | ||
{start_tabs} | ||
|
||
``` | ||
git clone https://github.com/zulip/python-zulip-api.git | ||
cd python-zulip-api | ||
python3 ./tools/provision | ||
``` | ||
1. {!download-python-bindings.md!} | ||
|
||
1. {!install-requirements.md!} | ||
|
||
1. Register a nick that ends with the suffix `_zulip` on your IRC server. | ||
|
||
This will create a new Python virtualenv. You'll run the bridge service | ||
inside this virtualenv. | ||
1. {!create-a-generic-bot.md!} | ||
|
||
1. Activate the virtualenv by running the `source` command printed | ||
at the end of the output of the previous step. | ||
1. Download the `zuliprc` configuration file of your bot by clicking the | ||
download (<i class="fa fa-download"></i>) icon under the bot's name, and | ||
save to `~/.zuliprc`. | ||
|
||
1. Go to the directory containing the bridge script if you haven't already done so | ||
1. [Subscribe the bot][subscribe-channels] to the Zulip channel where IRC | ||
messages should be mirrored. | ||
|
||
1. Begin mirroring messages between the IRC channel and the Zulip channel | ||
by running the `irc-mirror.py` script with the | ||
[required command-line arguments](#required-arguments). Use the | ||
[optional arguments](#optional-arguments) to configure the mirroring | ||
behavior. | ||
|
||
Here's an example command that mirrors messages between the | ||
**#python-mypy** channel on the `irc.freenode.net` server and the "mypy" | ||
topic on the **#irc-discussions** channel on Zulip: | ||
|
||
``` | ||
cd zulip/integrations/bridge_with_irc | ||
python {{ integration_path }}/irc-mirror.py \ | ||
--irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is |
||
--stream='irc-discussions' --topic='mypy' | ||
``` | ||
|
||
1. Install the bridge dependencies in your virtualenv, by running: | ||
1. Messages will be mirrored only when the terminal session with the bot | ||
remains open. Consider using `screen` to run the bot in the background. | ||
You can restart the integration at any time by re-running the | ||
`irc-mirror.py` script. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
We use it in the botserver (And zulip/zulip server), if you aren't familiar with it. |
||
{end_tabs} | ||
|
||
You're done! Messages in your Zulip channel may look like: | ||
|
||
``` | ||
pip install -r requirements.txt | ||
``` | ||
 | ||
|
||
### Configure the bridge | ||
Messages in your IRC channel may look like: | ||
|
||
1. {!create-a-generic-bot.md!} | ||
Download the bot's `zuliprc` configuration file to your computer. | ||
 | ||
|
||
1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip | ||
stream that will contain the mirror. | ||
[subscribe-channels]: /help/manage-user-channel-subscriptions#subscribe-a-user-to-a-channel | ||
|
||
1. Inside the virtualenv you created above, run: | ||
### Configuration options | ||
|
||
``` | ||
python irc-mirror.py --irc-server=IRC_SERVER --channel=<CHANNEL> --nick-prefix=<NICK> \ | ||
--stream=<STREAM> [--topic=<TOPIC>] \ | ||
--site=<zulip.site> --user=<bot-email> \ | ||
--api-key=<api-key> | ||
``` | ||
The integration script accepts the following command-line arguments: | ||
|
||
`--topic` is a Zulip topic, is optionally specified, defaults to "IRC". | ||
#### Required arguments | ||
|
||
Example command: | ||
- `--irc-server`: The IRC server to mirror. | ||
|
||
``` | ||
./irc-mirror.py --irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \ | ||
--stream='test here' --topic='#mypy' \ | ||
--site="https://chat.zulip.org" [email protected] \ | ||
--api-key=DeaDbEEf | ||
``` | ||
- `--nick-prefix`: Your registered IRC nick without the `_zulip` suffix. | ||
|
||
**Congratulations! You're done!** | ||
- `--channel`: The IRC channel to mirror. | ||
|
||
Your Zulip messages may look like: | ||
- `--stream`: The name of the Zulip channel you want to mirror. The default | ||
channel name is **#general**. | ||
|
||
 | ||
#### Optional arguments | ||
|
||
Your IRC messages may look like: | ||
- `--topic`: The name of the Zulip topic you want to receive and send | ||
messages in. The default topic name is "IRC". | ||
|
||
 | ||
- `--port`: The port to connect to the IRC server on. Defaults to 6667. | ||
|
||
- `--nickserv-pw`: Password corresponding to the IRC nick. | ||
|
||
- `--sasl-password`: Password for SASL authentication. |
Uh oh!
There was an error while loading. Please reload this page.