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
91 changes: 49 additions & 42 deletions zulip/integrations/bridge_with_irc/doc.md
Original file line number Diff line number Diff line change
@@ -1,67 +1,74 @@
# 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.

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 that will
contain the mirror.

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.

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}

```
pip install -r requirements.txt
```
You're done! Messages in your Zulip channel may look like:

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

1. {!create-a-generic-bot.md!}
Download the bot's `zuliprc` configuration file to your computer.
Messages in your IRC channel may look like:

1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip
stream that will contain the mirror.
![Zulip message on IRC](/static/images/integrations/irc/002.png)

1. Inside the virtualenv you created above, run:
[subscribe-channels]: /help/manage-user-channel-subscriptions#subscribe-a-user-to-a-channel

```
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>
```
### Configuration options

`--topic` is a Zulip topic, is optionally specified, defaults to "IRC".
The integration script accepts the following command-line arguments:

Example command:
#### Required arguments

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

**Congratulations! You're done!**
- `--nick-prefix`: Your registered IRC nick without the `_zulip` suffix.

Your Zulip messages may look like:
- `--channel`: The IRC channel to mirror.

![IRC message on Zulip](/static/images/integrations/irc/001.png)
- `--stream`: The name of the Zulip channel you want to mirror. The default
channel name is `#general`.

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

![Zulip message on IRC](/static/images/integrations/irc/002.png)
- `--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.
Loading