Skip to content
Permalink
Browse files

docs: Refactor installation page to quick install guide

This commit closes #118.

The existing documentation is divided into smaller, more manageable
pieces. While there are still improvements that could be made, the work
done across #120, #121, #122, and this commit is sufficient to close the
issue.
  • Loading branch information...
jwflory committed Feb 16, 2019
1 parent 767d39d commit b25d12c812e26705b350079ae93cdbf867f79ffb
Showing with 105 additions and 118 deletions.
  1. +1 −1 docs/index.rst
  2. +0 −117 docs/installation.rst
  3. +104 −0 docs/quick-install.rst
@@ -13,7 +13,7 @@ Today, it is used by various communities.
:maxdepth: 2
:caption: Contents

installation
quick-install
deploy-teleirc
config-file-glossary
who-uses-teleirc

This file was deleted.

@@ -0,0 +1,104 @@
#############
Quick install
#############

This is a quick installation guide for an administrator to configure and deploy Teleirc.
Teleirc configuration is divided into these steps:

#. Create a Telegram bot
#. Configure IRC channel
#. Configure and run Teleirc


*********************
Create a Telegram bot
*********************

.. note:: Teleirc **DOES NOT** support channels, only groups.
Read more about channels vs groups `here <https://telegram.org/faq#q-what-39s-the-difference-between-groups-supergroups-and-channel>`_.

Create a new Telegram bot to act as a bridge from the Telegram side.
The bot API provides a token key for the bot.
Use the bot to discover the unique chat ID of your Telegram group.

Create bot with BotFather
=========================

#. Send ``/start`` to @BotFather [#]_ user on Telegram
#. Follow instructions to create new bot (e.g. name, username, description, etc.)
#. Receive **token key** for new bot (used to access Telegram API)
#. (**REQUIRED**) Set ``/setprivacy`` to **DISABLED** (so bot can see messages) [#]_
#. Add bot to Telegram group you plan to bridge

Optional configuration changes
==============================

#. Set description or profile picture for your bot with @BotFather
#. Block your bot from being added to more groups (``/setjoingroups``)


*********************
Configure IRC channel
*********************

There is no required configuration for an IRC channel.
However, there are recommendations for best practices:

#. `Register your channel <https://docs.pagure.org/infra-docs/sysadmin-guide/sops/freenode-irc-channel.html#adding-new-channel>`_
#. Give permanent voice to your bridge bot via **ChanServ** (most networks use the ``+V`` flag)
- *Example*: On freenode, ``/query ChanServ ACCESS #channel ADD my-teleirc-bot +V``


*************************
Configure and run Teleirc
*************************

This section explains how to configure and install Teleirc itself.

Requirements
============

- git
- nodejs (v8 and v10 supported)
- `yarn <https://yarnpkg.com/en/docs/install>`_

Install dependencies
====================

#. Clone the repository (``git clone https://github.com/RITlug/teleirc.git``)
#. Install dependencies (``yarn``)

Configuration
=============

Teleirc uses `dotenv <https://www.npmjs.com/package/dotenv>`_ to manage API keys and settings.
The config file you use is a ``.env`` file.
Copy the example file to a production file to get started (``cp env.example .env``).
Edit the ``.env`` file with your API keys and settings.

.. seealso::

See :doc:`config-file-glossary` for detailed information.

Relay Telegram picture messages via Imgur
-----------------------------------------

Teleirc retrieves picture messages via the Telegram API.
By default, picture messages from Telegram are viewable from the given Telegram API URL.
However, API links expire and eventually break.
Optionally, Teleirc uploads an image to Imgur and replaces the Telegram API URL with a link to Imgur instead.
This makes picture messages more durable for logs or for someone joining the conversation later.

To add Imgur support, follow these steps:

#. Create an Imgur account
#. `Register your bot <https://api.imgur.com/oauth2/addclient>`_ with the Imgur API
- Select *OAuth2 without callback* option
#. Put client ID into ``.env`` file and enable using Imgur


.. [#] @BotFather is the `Telegram bot <https://core.telegram.org/bots>`_ for `creating Telegram bots <https://core.telegram.org/bots#6-botfather>`_
.. [#] Privacy setting must be disabled for Teleirc bot to see messages in the Telegram group.
By default, bots cannot see messages unless a person uses a command to interact with the bot.
Since Teleirc forwards all messages, it needs to see all messages.
Messages are not stored or tracked by Teleirc.

0 comments on commit b25d12c

Please sign in to comment.
You can’t perform that action at this time.