mirror of
https://github.com/zulip/zulip.git
synced 2025-11-03 13:33:24 +00:00
irc: Improve the IRC and Matrix documentation.
The big changes here are: * Making the install instructions easier to copy/paste. * Adding numbering for the IRc integration. We probably want to do a similar thing with Matrix, too.
This commit is contained in:
Tim Abbott
@@ -1,66 +1,84 @@
|
||||
A bridge for exchanging messages between IRC and Zulip! (Using
|
||||
`matrix_client`)
|
||||
A bridge for exchanging messages between IRC and Zulip, powered by
|
||||
[the Zulip Matrix integration](/integrations/doc/matrix).
|
||||
|
||||
### Setup the bridge:
|
||||
### Install the bridge software
|
||||
|
||||
1. `git clone https://github.com/zulip/python-zulip-api.git` - clone the [python-zulip-api](
|
||||
https://github.com/zulip/python-zulip-api) repository.
|
||||
You can install the bridge software as follows:
|
||||
|
||||
2. `cd python-zulip-api` - navigate into your cloned repository and use
|
||||
`python3 ./tools/provision` to install all requirements in a Python virtualenv.
|
||||
1. First, clone the Zulip API and install its dependencies:
|
||||
|
||||
3. The output of `provision` will end with a command of the form `source .../activate`;
|
||||
run that command to enter the new virtualenv.
|
||||
```
|
||||
git clone https://github.com/zulip/python-zulip-api.git
|
||||
cd python-zulip-api
|
||||
python3 ./tools/provision
|
||||
```
|
||||
|
||||
4. Navigate to the
|
||||
[matrix integration](https://github.com/zulip/python-zulip-api/tree/master/zulip/integrations/matrix)
|
||||
and use `pip install -r requirements.txt` to install the dependencies.
|
||||
1. Next, enter the virtualenv, by running the `source` command printed
|
||||
at the end of the `provision` output.
|
||||
|
||||
Now you can start the next configuration step.
|
||||
1. Then, run this to install the Matrix bridge software in your virtualenv.
|
||||
|
||||
### Configure the bridge:
|
||||
```
|
||||
pip install -r zulip/integrations/matrix/requirements.txt
|
||||
```
|
||||
|
||||
This will create a new Python virtual environment, with all the
|
||||
dependences for this bridge installed. You'll want to run the bridge
|
||||
service inside this virtualenv. If you later need to enter the
|
||||
virtualenv (from e.g. a new shell), you can use the `source` command.
|
||||
|
||||
### Configure the bridge
|
||||
|
||||
{!create-stream.md!}
|
||||
|
||||
Next, on your Zulip settings page, create a generic bot for Matrix, preferably with
|
||||
a formal name like `irc-bot`.
|
||||
It is important that you subscribe this bot to the stream which is going
|
||||
to act as the bridge.
|
||||
Note its username, API key and full name; you will use them in the
|
||||
next step.
|
||||
1. Next, on your Zulip settings page, create a generic bot for Matrix,
|
||||
preferably with a formal name like `irc-bot`.
|
||||
|
||||
1. Subscribe this bot to the Zulip stream where you'd like the bridge
|
||||
traffic to be sent.
|
||||
|
||||
1. Edit `zulip/integrations/matrix/matrix_bridge_config.py`, providing
|
||||
the following values for the `zulip` section (the first 3 values
|
||||
come from a `zuliprc` file):
|
||||
|
||||
In `matrix_bridge_config.py` enter the following details under `zulip`
|
||||
keyword:
|
||||
```
|
||||
"zulip": {
|
||||
"email": "matrix-bot@chat.zulip.org",
|
||||
"api_key": "your_key",
|
||||
"site": "https://chat.zulip.org",
|
||||
"stream": "Stream which acts as the bridge",
|
||||
"topic": "Topic of the stream"
|
||||
}
|
||||
```
|
||||
Now, create a user on [matrix.org](https://matrix.org/), preferably with a formal
|
||||
name like `zulip-bot`.
|
||||
|
||||
Matrix has been bridged to the listed
|
||||
1. Now, create a user on [matrix.org](https://matrix.org/), preferably
|
||||
with a formal name like `zulip-bot`.
|
||||
Matrix has been bridged to several popular
|
||||
[IRC Networks](https://github.com/matrix-org/matrix-appservice-irc/wiki/Bridged-IRC-networks),
|
||||
where the `Room alias format` refers to the `room_id` for the corresponding IRC channel.
|
||||
For example, the `room_id` would be `#freenode_#zulip-test:matrix.org`
|
||||
for the freenode channel `#zulip-test`.
|
||||
where the `Room alias format` refers to the `room_id` for the
|
||||
corresponding IRC channel. For example, the `room_id` would be
|
||||
`#freenode_#zulip-test:matrix.org` for the freenode channel
|
||||
`#zulip-test`.
|
||||
|
||||
1. Edit `matrix_bridge_config.py` to add the Matrix-side settings:
|
||||
|
||||
In `matrix_bridge_config.py` enter the follow details under `matrix` keyword:
|
||||
```
|
||||
"matrix": {
|
||||
"host": "https://matrix.org",
|
||||
"username": "username of matrix.org user",
|
||||
"password": "password of matrix.org user",
|
||||
"room_id": "#room:matrix.org"
|
||||
}
|
||||
```
|
||||
|
||||
If you want to change the displayed message template in Matrix or Zulip,
|
||||
change the variables `MATRIX_MESSAGE_TEMPLATE` and `ZULIP_MESSAGE_TEMPLATE`,
|
||||
with a suitable template.
|
||||
1. After the steps above have been completed, run `python matrix_bridge.py` to
|
||||
start mirroring content.
|
||||
|
||||
After the steps above have been completed, run `python matrix_bridge.py` to
|
||||
start the mirroring.
|
||||
If you want to customize the message formatting, you can do so by
|
||||
editing the variables `MATRIX_MESSAGE_TEMPLATE` and
|
||||
`ZULIP_MESSAGE_TEMPLATE` in
|
||||
`zulip/integrations/matrix/matrix_bridge.py`, with a suitable
|
||||
template.
|
||||
|
||||
**Congratulations! You have created the bridge successfully!**
|
||||
|
||||
@@ -74,7 +92,7 @@ Your IRC notifications may look like:
|
||||
|
||||
|
||||
|
||||
### Caveats for IRC mirroring
|
||||
### Caveats
|
||||
|
||||
There are certain
|
||||
[IRC channels](https://github.com/matrix-org/matrix-appservice-irc/wiki/Channels-from-which-the-IRC-bridge-is-banned)
|
||||
|
||||
@@ -1,23 +1,32 @@
|
||||
A bridge for exchanging messages between Matrix and Zulip!
|
||||
A bridge for exchanging messages between [matrix.org](https://matrix.org) and Zulip!
|
||||
|
||||
### Setup the bridge:
|
||||
### Install the bridge software
|
||||
|
||||
1. `git clone https://github.com/zulip/python-zulip-api.git` - clone the [python-zulip-api](
|
||||
https://github.com/zulip/python-zulip-api) repository.
|
||||
You can install the bridge software as follows:
|
||||
|
||||
2. `cd python-zulip-api` - navigate into your cloned repository and use
|
||||
`python3 ./tools/provision` to install all requirements in a Python virtualenv.
|
||||
1. First, clone the Zulip API and install its dependencies:
|
||||
|
||||
3. The output of `provision` will end with a command of the form `source .../activate`;
|
||||
run that command to enter the new virtualenv.
|
||||
```
|
||||
git clone https://github.com/zulip/python-zulip-api.git
|
||||
cd python-zulip-api
|
||||
python3 ./tools/provision
|
||||
```
|
||||
|
||||
4. Navigate to the
|
||||
[matrix integration](https://github.com/zulip/python-zulip-api/tree/master/zulip/integrations/matrix)
|
||||
and use `pip install -r requirements.txt` to install the dependencies.
|
||||
1. Next, enter the virtualenv, by running the `source` command printed
|
||||
at the end of the `provision` output.
|
||||
|
||||
Now you can start the next configuration step.
|
||||
1. Then, run this to install the Matrix bridge software in your virtualenv.
|
||||
|
||||
### Configure the bridge:
|
||||
```
|
||||
pip install -r zulip/integrations/matrix/requirements.txt
|
||||
```
|
||||
|
||||
This will create a new Python virtual environment, with all the
|
||||
dependences for this bridge installed. You'll want to run the bridge
|
||||
service inside this virtualenv. If you later need to enter the
|
||||
virtualenv (from e.g. a new shell), you can use the `source` command.
|
||||
|
||||
### Configure the bridge
|
||||
|
||||
{!create-stream.md!}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user