Installation

This page is an installation guide for a server administrator to install and run Teleirc. The person who installs Teleirc will have elevated privileges to maintain and administrate the Telegram bot.

There are three parts to installing and configuring Teleirc:

  1. Create a Telegram bot
  2. Configure and run Teleirc
  3. Configure IRC channel

Create a Telegram bot

Create a new Telegram bot to act as a bridge from the Telegram side. From the bot API, you will receive a token key for the bot. You will then use the bot obtain the unique chat ID of your Telegram group.

Create bot with API

  1. Send /start in a message to @BotFather [1] user on Telegram
  2. Follow instructions from @BotFather to create new bot (e.g. name, username, description, etc.)
  3. Receive token key for new bot (used to access Telegram API)
  4. (Optional) Set description or profile picture for your bot with @BotFather
  5. (Required) Set /setprivacy to DISABLED (so bot can see messages) [2]
  6. Add bot to Telegram group you plan to bridge
  7. (Optional) Block your bot from being added to more groups (/setjoingroups)

All configuration on Telegram side is complete.

Configure and run Teleirc

There are several installation options available. This guide details the supported method to configure and run Teleirc. For alternative options, read further below (for Dockerfiles, distro-specific packages, etc.).

Requirements

  • git
  • nodejs (8.x.x) – we strongly recommend nvm as the installation method.

Download

  1. Clone the repository to the server

    • git clone https://github.com/RITlug/teleirc.git

  2. Change directories to repo

  3. Install yarn via one of the following methods (we will only Linux, yarn install documentation cover the rest)

    • Arch Linux
    pacman -S yarn
    • Debian/Ubuntu
    curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update ; sudo apt-get install --no-install-recommends yarn
    • Fedora/CentOS/RHEL:
    curl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.repo
yum install yarn or dnf install yarn

  4. Install dependencies using yarn

    • yarn

Configuration

Teleirc uses dotenv for easy management of API keys and settings. All your configuration changes will live in the .env file. You should not need to change other files. This makes it possible to use git pull to upgrade the bot in-place.

Explaining config file

The config file you use is a .env file. All configuration values for Teleirc are stored here. Copy the example file to a productive file to get started (cp .env.example .env) Edit the .env file and configure it your preference.

Explanations of the configuration values are below.

IRC

  • IRC_BLACKLIST:

    • Comma-separated list of IRC nicks to ignore (default: "")

  • IRC_BOT_NAME:

    • Nickname for your bot to use on IRC (default: teleirc)

  • IRC_CHANNEL:

    • IRC channel you want your bot to join (default: #channel)

  • IRC_SEND_STICKER_EMOJI:

    • Send the emoji associated with a sticker on IRC (default: true)

  • IRC_PREFIX:

    • Text displayed before Telegram name in IRC (default: "<")

  • IRC_SUFFIX:

    • Text displayed after Telegram name in IRC (default: ">")

  • IRC_SERVER:

    • IRC server you wish to connect to (default: chat.freenode.net)
Telegram

Note

teleirc DOES NOT support channels, only groups. Read more about channels vs groups here.

  • TELEIRC_TOKEN:

    • Private API token for Telegram bot

  • MAX_MESSAGES_PER_MINUTE:

    • Maximum rate at which to relay messages (default: 20)

  • SHOW_ACTION_MESSAGE:

    • Relay action messages (default: true)

  • SHOW_JOIN_MESSAGE:

    • Relay join messages (default: false)

  • SHOW_KICK_MESSAGE:

    • Relay kick messages (default: false)

  • SHOW_LEAVE_MESSAGE:

    • Relay leave messages (default: false)

  • TELEGRAM_CHAT_ID:

Imgur

  • USE_IMGUR_FOR_IMAGES:

    • Upload picture messages from Telegram to Imgur, convert picture to Imgur link in IRC (default: false)

  • IMGUR_CLIENT_ID:

    • Imgur API client ID value to access Imgur API

Imgur support

Teleirc retrieves images via the Telegram API. By default, picture messages from Telegram will link to the Telegram API URL. However, the links expire and are not reliable. Optionally, Teleirc can upload an image to Imgur and replace the Telegram API URL with a link to Imgur. This makes picture messages more durable for logs or someone joining the conversation later.

To add Imgur support, follow these steps:

  1. Create an Imgur account, if you do not have one

  2. Register your bot with the Imgur API

    • Select OAuth2 without callback option

  3. Put client ID into .env file and enable using Imgur

Usage

Choose how you want to run Teleirc persistently. Teleirc officially supports three methods.

pm2

pm2 is a NPM package that keeps NodeJS running in the background. If you run an application and it crashes, pm2 restarts the process. pm2 also restarts processes if the server reboots.

Read the pm2 documentation for more information.

After pm2 is installed, follow these steps to start Teleirc:

cd teleirc/
pm2 start -n teleirc-channel teleirc.js

systemd

systemd is an option to run the bot persistently. A provided systemd service file is available (misc/teleirc.service) Move the provided file to /usr/lib/systemd/system/ to activate it. Now, you can manage Teleirc through standard systemctl commands.

Note that the provided file makes two assumptions:

  • Using a dedicated system user (e.g. teleirc)
  • Home directory located at /usr/lib/teleirc/ (i.e. files inside Teleirc repository)

screen / tmux

Terminal multiplexers like GNU screen and tmux let you run Teleirc persistently. If you are not familiar with a multiplexer, read more about tmux here.

Inside of your persistent window, follow these steps to start Teleirc:

cd teleirc/
node teleirc.js

ArchLinux

On ArchLinux, teleirc is available in the AUR. The AUR package uses the systemd method for running Teleirc. Configure the bot as detailed above in the /usr/lib/teleirc/ directory.

Docker

See also

See Using Docker for more information

Configure IRC channel

Depending on the IRC network you use, no configuration in IRC is required. However, there are recommendations for best practices to follow.

  • Register your channel
  • Give permanent voice to your bridge bot via NickServ (for most networks, the +Vv flags)
    • Example: For freenode, /query NickServ ACCESS #channel ADD my-teleirc-bot +Vv
[1]@BotFather is the Telegram bot for creating Telegram bots
[2]Privacy setting must be changed for the bot to see messages in the Telegram group. By default, bots cannot see messages unless they use a command to interact with the bot. Since Teleirc forwards all messages, it needs to see all messages. This is why this setting must be changed.