From 2d9ada5101f11c55545e42f2cc1a5ed8c8dae3d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ezequiel=20P=C3=A1ssaro?= Date: Fri, 18 Dec 2020 18:07:47 -0300 Subject: [PATCH] Update Matterbridge docs (#1395) * update mattebridge docs * fix typo * Apply suggestions from code review Co-authored-by: Andrew * minor changes * change page title * add link to repo * nice changes Co-authored-by: Andrew --- docs/development/matterbridge.inc | 3 +- docs/development/matterbridge.rst | 103 +++++++++++++++++------------- 2 files changed, 62 insertions(+), 44 deletions(-) diff --git a/docs/development/matterbridge.inc b/docs/development/matterbridge.inc index 0bfa8d1e77b..a552ef4bfdf 100644 --- a/docs/development/matterbridge.inc +++ b/docs/development/matterbridge.inc @@ -1,10 +1,11 @@ .. matterbridge stuff .. _OpenSupernova.org: http://opensupernova.org +.. _private GitHub repository: https://github.com/tardis-sn/tardis-matterbridge .. _Upstart script: https://www.digitalocean.com/community/tutorials/the-upstart-event-system-what-it-is-and-how-to-use-it .. _Systemd service: https://freedesktop.org/software/systemd/man/systemd.service.html .. _steps for Slack in the Matterbridge wiki: https://github.com/42wim/matterbridge/wiki/Slack-bot-setup +.. _steps for Mattermost in the Matterbridge wiki: https://github.com/42wim/matterbridge/wiki/Section-Mattermost-%28basic%29 .. _this comment: https://github.com/42wim/matterbridge/issues/964#issuecomment-612721850 .. _this link: https://developer.gitter.im/docs/authentication .. _releases section: https://github.com/42wim/matterbridge/releases/latest - diff --git a/docs/development/matterbridge.rst b/docs/development/matterbridge.rst index 7f4b3c45d2c..3d3fef39d8a 100644 --- a/docs/development/matterbridge.rst +++ b/docs/development/matterbridge.rst @@ -1,44 +1,46 @@ -************ -Matterbridge -************ +******************* +Matterbridge Server +******************* ======== Overview ======== We use Matterbridge to connect channels across different messaging platforms -such as Slack, Mattermost and Gitter. Matterbridge provides binaries for many -operating systems. These files are intended to be used in combination with -TOML configuration files:: +such as *Slack*, *Mattermost* and *Gitter*. Matterbridge provides binaries +for many operating systems. The ``matterbridge`` binary is intended to be used +in combination with a TOML configuration file:: $ ./matterbridge -conf config-tardis-matterbridge.toml -The TOML file includes all the configuration needed to connect as many -messaging platforms as you want, including tokens and passwords. +The TOML file includes all the parameters required to connect as many +messaging platforms as you want, like *tokens* and *passwords*. Once the +application is running, messages can be shared between the connected rooms. -Currently, we keep a service running on `OpenSupernova.org`_ server to keep -running Matterbridge as a daemon. Our configuration files are stored in the -private repository ``tardis-matterbridge``. These files include our custom -TOML configuration file and the files needed to set up the Linux service. +Currently, we keep a service running on the `OpenSupernova.org`_ server to +run Matterbridge as a daemon. Our configuration files are stored in a `private +GitHub repository`_, including our custom TOML and the files needed to set up the +Linux service. -Since this server runs Ubuntu 14.04 we use an `Upstart script`_ instead a -`Systemd service`_ file. But a *Systemd* file is also included in -``tardis-matterbridge`` repository, just in case. +Since this server runs Ubuntu 14.04 we use an `Upstart script`_ instead of a +`Systemd service`_ file, but a Systemd file is also included in our repository. +A *cron* job restarts the service periodically to prevent disconnections. -===== -Setup -===== +============= +Configuration +============= Use the TOML file in ``tardis-matterbridge`` as an example. You can set up -as many gateways as you want. +as many gateways as you want! + ----- Slack ----- Follow the `steps for Slack in the Matterbridge wiki`_ and read carefully -`this comment`_. Do not add any scopes manually. Copy the token to use later -in the TOML file. +`this comment`_ (do not add any scopes manually!). Copy the token to use +later in the TOML file. ------ @@ -46,36 +48,51 @@ Gitter ------ Create a new GitHub dedicated account to use as a bot, refer to `this link`_ -and copy the token. +and copy the token to use later in the TOML file. + + +---------- +Mattermost +---------- +Follow the `steps for Mattermost in the Matterbridge wiki`_. ----------------------------------------- -Setting up the server for the first time ----------------------------------------- -Follow these steps to set up the server for the first time: +================ +First-time setup +================ -1. *ssh* to `OpenSupernova.org`_ -2. Download the Matterbridge binary for Linux from the `releases section`_ -3. Make the file executable and rename it to ``matterbridge`` -4. Copy ``matterbridge`` executable to ``/usr/local/bin`` -5. Clone ``tardis-matterbridge`` repository -6. Copy ``config-tardis-matterbridge.toml`` to ``/usr/local/etc/matterbridge/`` -7. Copy ``matterbridge.conf`` to ``/etc/init/`` -8. Run ``sudo service matterbridge start`` -9. Test your gateways +Follow these steps to set up the server: +1. *ssh* to `OpenSupernova.org`_ server. +2. Download the Matterbridge binary for Linux from the `releases section`_. +3. Make the file executable and rename it to ``matterbridge``. +4. Copy ``matterbridge`` executable to ``/usr/local/bin``. +5. Clone ``tardis-matterbridge`` repository in your ``$HOME``. +6. Copy ``config-tardis-matterbridge.toml`` to ``/usr/local/etc/matterbridge/``. +7. Copy ``matterbridge.conf`` to ``/etc/init/``. +8. Run ``sudo service matterbridge start``. +9. Test your gateways. -------------------- -Adding new gateways -------------------- + +=========================== +Update server configuration +=========================== After updating the TOML file, follow these steps: -1. *ssh* to `OpenSupernova.org`_ -2. Copy your new ``config-tardis-matterbridge.toml`` to ``/usr/local/etc/matterbridge/`` -3. Run ``sudo service matterbridge restart`` -4. Test your gateways -5. If everything is ok, make a pull request to ``tardis-matterbridge`` with your new TOML file +1. *ssh* to `OpenSupernova.org`_ server. +2. Copy your new ``config-tardis-matterbridge.toml`` to ``/usr/local/etc/matterbridge/``. +3. Run ``sudo service matterbridge restart``. +4. Test your gateways. +5. If everything is ok, make a pull request to ``tardis-matterbridge`` with your new TOML file. + + +======== +Cron job +======== + +To edit the cron job, *ssh* to `OpenSupernova.org`_ and run ``sudo crontab -e``. + .. include:: matterbridge.inc