+--------------+
| Introduction |
+--------------+
We run a bridge between the #replicant channel on OFTC and the #replicant
channel on liberachat. This is because we originally started on Freenode,
but we found out that it was not possible to create accounts with Tor in
Freenode so we also opened a #replicant channel on the OFTC network to
also enable users that want to protect their identity to be able to join
the replicant channel.

+--------------+
| Requirements |
+--------------+
To deploy the Replicant IRC bridge, you need:
- To have the OFTC network and libreachat networks configured in an IRC
  client in a way that enforces encryption and checks for certificates validity.
  More precisely:
  - TLS should be used for both OFTC and Libera.Chat
  - SASL should be used for Libera.Chat.
  This is to avoid sending passwords in clear.
- Access to the Replicant contact address to change the passwords
- A virtual or physical computer that can stay always on
- The ability to run FSDG compliant distributions in that computer
- The ability to run matterbridge (the bridge software) on the distribution you
  use. Since at the time of writing, we don't have matterbridge packaged in
  Trisquel 9, we used Guix to install matterbridge in Trisquel 9.

If you intend to deploy a similar configuration for other purposes some of the
requirements above could be removed.

+------------+
| Deployment |
+------------+

We want to avoid passing around password in insecure ways. So the way to
re-deploy this bridge is to first change the passwords, then add the new
passwords in the configuration file and run matterbridge.

Changing passwords:
-------------------
You will first need to shut down the actual bridge if it's already running as
this tutorial doesn't take in account cases where you lost control of a running
bridge for some reasons. If that happens you might need to kick the old bridge
from IRC first or prevent it from login in with the Replicant-bridge username
after having changed the password.

Once done, you can either start with Libera.chat or OFTC, but you'll need to do
both.

Changing the liberachat password:
---------------------------------
To change the password you first need to connect to liberachat securely.

Once done, you can request a password change with the following command:
/msg NickServ SENDPASS Replicant-bridge

The instructions to change the password will then arrive at the Replicant
contact address.

Once the password has been changed you will need to update it in the
password in the configuration file(s).

Once this is done, make sure that your IRC client is not connected (anymore)
as Replicant-bridge.

Changing the OFTC password:
---------------------------
We still need to find out how to change password in the OFTC network.

Deploying the matterbridge binary on Trisquel 9:
------------------------------------------------
To install matterbridge, you can run the following commands:
$ make matterbridge.tar.xz
$ sudo tar xf matterbridge.tar.xz -C /
$ sudo ./post-install.sh

Deploying the matterbridge.toml configuration file:
---------------------------------------------------
To generate the matterbridge.toml configuration, you need to either copy
the matterbridge.example file manually to /etc/matterbridge.toml and fill
in the passwords, or you could also add your passwords in a .netrc file either
in the current directory or in ~/.netrc.

The netrc file should have lines that looks like that (with different
passwords):
machine irc.liberachat password Hdrgdx7dRkHsPO16UgS8rkzP8lHgJQ/O1qSsHqGBtnUkC1/g
machine irc.OFTC password jsRb4dmIAx7cgfr0EfkGqINcqs9Duq7JRfHkvKDSetezi7oxKqefOB

You will then be able to generate the matterbridge.toml with the following
command:
$ make matterbridge.toml

You will then need to copy it to /etc/matterbridge.toml in the server that will
run the matterbridge binary.

Starting matterbridge:
----------------------
As we the matterbridge tarball ships a  systemd service file as well you can
simply use regular systemd commands:
$ sudo systemctl start matterbridge
$ sudo systemctl enable matterbridge

For the logs, matterbridge is also integrated with journald, so you can simply
use the following command to follow what is going on:
$ journalctl -u matterbridge -f