Bridge Setup

This guide is written for server administrators who would like to set up their own IRC bridge to one or more networks.

Before setting up

We recommend using Node.js v16 or greater when setting up the bridge, as we use worker_threads to handle some of the traffic for larger bridges.

Versions older than Node 16 are no longer supported.

You should also ensure you have a recent Matrix homeserver that you have permission to bridge to. This can either be your own, or one that you have the ability to setup Application Services with.

Finally you should seek permission from the operator of the bridged IRC network before running this bridge. Bridging may be against the IRC network's Terms of Use.. Failure to do so may get your bridge banned and your IP address blocked by the IRC network. Most networks will only allow a limited number of IRC connections from a single IP, so you should ask them for permission before bridging.

1. Installation

Install from git (preferred)

git clone https://github.com/matrix-org/matrix-appservice-irc.git
cd matrix-appservice-irc
git checkout master # or 0.x.x to pin to a version
yarn

The bridge can now be started by: node app.js.

Global Install

# --global requires super user on most systems
$ yarn install --global matrix-appservice-irc

Docker

The bridge has a Docker image.

2. Configuration

The bridge must be configured before it can be run. This tells the bridge where to find the homeserver and how to bridge IRC channels/users.

Copy config.sample.yaml to config.yaml.
- For Docker, you will want to make a directory called data and store the config.yaml inside.
Modify config.yaml to point to your homeserver and IRC network of choice.

The sample config has detailed information about each option. Please read them carefully.

3. Database

The bridge comes with support for either PostgreSQL or NEDB. PostgreSQL is preferred as it is faster, easier to handle than flat files and allows you to inspect the state of it while the bridge is running.

Setting up PostgresSQL for the bridge is as easy as doing:

-- Authenticate with postgres, then
psql 'postgres://dbstring'
CREATE DATABASE ircbridge;
CREATE USER ircbridge WITH PASSWORD 's3cr3t';
GRANT ALL ON DATABASE ircbridge TO ircbridge;
-- Then modify your config.yaml to include the database connection string.

4. Registration

The bridge needs to generate a registration file which can be passed to the homeserver to tell the homeserver which Matrix events the bridge should receive.

Execute the following command:

node app.js -r -f appservice-registration-irc.yaml -u "http://localhost:8090" -c config.yaml -l my_bot

Change -u "http://localhost:8090" to wherever your Matrix server can contact this IRC bridge. By changing the option -l my_bot you can modify the localpart of the bridge bot user. It contacts Matrix users of your bridge to control their usage of the bridge (e.g. to change their nickname).

You should get something like:

id: irc
hs_token: 82c7a893d020b5f28eaf7ba31e1d1091b12ebafc5ceb1b6beac2b93defc1b301
as_token: a66ae41f82b05bebfc9c259135ce1ce35c856000d542ab5d1f01e0212439d534
namespaces:
  users:
    - exclusive: true
      regex: '@irc_.*:yourhomeserverdomain'
  aliases:
    - exclusive: true
      regex: '#irc_.*:yourhomeserverdomain'
url: 'http://localhost:8090'
sender_localpart: appservice-irc
rate_limited: false
protocols:
  - irc

For Docker, copy the above to data/appservice-registration-irc.yaml and replace as necessary.

More information on the CLI args can be found by running $ node app.js --help.

This will create a registration YAML file. Edit your homeserver config file (e.g. homeserver.yaml) to point to this registration file:

# homeserver.yaml
app_service_config_files: ["appservice-registration-irc.yaml"]

5. Running

Finally, the bridge can be run using the following command:

$ node app.js -c config.yaml -f appservice-registration-irc.yaml -p 8090

Or for Docker:

# Remember to expose ports for metrics, debug API if you need to.
docker run --volume $PWD/data:/data --publish 8090 matrixdotorg/matrix-appservice-irc

Matrix IRC Bridge