README: improve deployment documentation

I originally added it to the wiki but it's probably better to move
it back here to be updated along with the code and configuration.

Signed-off-by: Denis 'GNUtoo' Carikli <GNUtoo@cyberdimension.org>

1 files changed, 90 insertions, 5 deletions

diff --git a/README.txt b/README.txt
index e4ad5c1..403d781 100644
--- a/README.txt
+++ b/README.txt
@@ -1,20 +1,105 @@
-== Deployment ==
++--------------+
+| 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/gqo3lmEuzaWeJw6FmnS/6fotKCxZV
-machine irc.OFTC password jsRb4dmIAx7cgfr0EfkGqINcqs9Duq7JRfHkvKDSetezi7oxKqefOBMLmIDKjvQhlmBcYTrGKVYZ
+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.
+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