Skip to content

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 52 additions & 42 deletions zulip/integrations/bridge_with_irc/doc.md
Original file line number Diff line number Diff line change
@@ -1,67 +1,77 @@
# Zulip IRC Integration

Mirror an IRC channel in Zulip!

### Install the bridge software
{start_tabs}

1. Clone the Zulip API repository, and install its dependencies.
1. {!download-python-bindings.md!}

```
git clone https://github.com/zulip/python-zulip-api.git
cd python-zulip-api
python3 ./tools/provision
```
1. {!install-requirements.md!}

1. Register a nick that ends with the suffix "_zulip" on your IRC server.

1. {!create-a-generic-bot.md!}

This will create a new Python virtualenv. You'll run the bridge service
inside this virtualenv.
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. Activate the virtualenv by running the `source` command printed
at the end of the output of the previous step.
1. [Subscribe the bot][subscribe-channels] to the Zulip channel that will
contain the mirror.

1. Go to the directory containing the bridge script if you haven't already done so
1. Mirror the IRC channel to 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.

1. Here's an example command that mirrors the `#python-mypy` channel on the
`irc.freenode.net` server to 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 \
--stream='irc-discussions' --topic='mypy'
```

1. Install the bridge dependencies in your virtualenv, by running:
{end_tabs}

You're done!

Your Zulip messages may look like:

![IRC message on Zulip](/static/images/integrations/irc/001.png)

```
pip install -r requirements.txt
```
Your IRC messages may look like:

### Configure the bridge
![Zulip message on IRC](/static/images/integrations/irc/002.png)

1. {!create-a-generic-bot.md!}
Download the bot's `zuliprc` configuration file to your computer.
[subscribe-channels]: /help/manage-user-channel-subscriptions#subscribe-a-user-to-a-channel

1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip
stream that will contain the mirror.
### Configuration options

1. Inside the virtualenv you created above, run:
The integration script accepts the following command-line arguments:

```
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>
```
#### Required arguments

`--topic` is a Zulip topic, is optionally specified, defaults to "IRC".
- `--irc-server`: The IRC server to mirror.

Example command:
- `--nick-prefix`: Your registered IRC nick must always end with "_zulip".
Use the prefix of your IRC nick without the "_zulip" suffix.

```
./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
```
- `--channel`: The IRC channel to mirror.

**Congratulations! You're done!**
- `--stream`: The name of the Zulip channel you want to receive
notifications in. By default, messages are sent to the `general` channel.

Your Zulip messages may look like:
#### Optional arguments

![IRC message on Zulip](/static/images/integrations/irc/001.png)
- `--topic`: The name of the Zulip topic you want to receive notifications
in. By default, messages are sent to the "IRC" topic.

Your IRC messages may look like:
- `--port`: The port to connect to the IRC server on. Defaults to 6667.

![Zulip message on IRC](/static/images/integrations/irc/002.png)
- `--nickserv-pw`: Password corresponding to the IRC nick.

- `--sasl-password`: Password for SASL authentication.
Loading