Quick Start Guide

This page is a quick start guide to using TeleIRC. It is an overview of how to install, set up, and deploy TeleIRC v2.x.x releases. Note this does not apply to v1.x.x releases; see the v1.3.4 documentation.

Contents

  1. Overview

    1. Telegram Channels

  2. Create a Telegram bot

    1. Create bot with BotFather

    2. Optional BotFather tweaks

  3. Configure IRC channel

    1. IRC channel overview

    2. Configure a Freenode IRC channel

    3. Configure Imgur Image Upload (IIU)

  4. Deployment Guide

    1. Run binary

      1. Pre-requirements

      2. Build TeleIRC

      3. Configuration

      4. Start bot

        1. Example Linux setup

    2. Run container

Overview

This section is a written, high-level overview of how to configure and deploy a TeleIRC bot. The Quick Start Guide will cover these topics:

  1. Create a Telegram bot to obtain a Telegram API token

  2. Set up an IRC channel for best user experience

  3. Deploy TeleIRC to your system

It is important each step is followed exactly and in order. Missing a step or skipping a section often results in common frustrations, such as one-way relay of chat messages.

Telegram Channels

TeleIRC DOES NOT support Telegram Channels, only groups. Read more on the differences between channels and groups in the Telegram FAQ.

Create a Telegram bot

TeleIRC requires a Telegram API token in order to access messages in a Telegram group. To obtain a token, someone must register a new Telegram bot. The Telegram bot will appear as the Sending User in Telegram for all IRC messages.

Create bot with BotFather

BotFather is the Telegram bot for creating Telegram bots. See the official Telegram documentation for how to create a new bot.

Once you create a new bot, you must follow these additional steps (IN EXACT ORDER) for TeleIRC:

  1. Send /setprivacy to @BotFather, change to Disable why?

  2. Add bot to Telegram group to be bridged

  3. Send /setjoingroups to @BotFather, change to Disable why?

Optional BotFather tweaks

  1. Set a description or add profile picture for your bot

  2. Block your bot from being added to more groups (/setjoingroups)

Configure IRC channel

This section explains best practices for configuring IRC channels for TeleIRC. Because IRC networks can run different software, exact instructions may differ depending on your IRC network. So, this section is divided in two ways:

  1. High-level overview of how to set up your IRC channel

  2. How to actually do it on Freenode IRC network

IRC channel overview

No matter what IRC network you use, TeleIRC developers recommend this IRC channel configuration:

  • Register your IRC channel with the IRC network (i.e. ChanServ).

  • Unauthenticated users may join the channel.

  • Only authenticated users may write in the channel (i.e. NickServ).

  • Any user connecting from a network-recognized gateway (e.g. web chat) with an assigned hostmask automatically receives voice on join (and thus, does not need to authenticate to write in channel).

  • TeleIRC bot hostmask automatically receives voice on join (and thus, does not need to authenticate to write in channel).

  • IRC channel operators automatically receive operator privilege on join.

Configure a Freenode IRC channel

If your IRC channel is on the Freenode IRC network, use these exact commands to create a channel policy as described above:

  1. /join #channel

  2. /query ChanServ REGISTER #channel

  3. /query ChanServ SET #channel GUARD on

  4. /query ChanServ ACCESS #channel ADD <NickServ account> +AORfiorstv (repeat for each IRC user who needs admin access) (what do these mean?)

  5. /query ChanServ SET mlock #channel +Ccnt

  6. /mode #channel +q $~a

  7. /query ChanServ ACCESS #channel ADD *!*@gateway/* +V

  8. /query ChanServ ACCESS #channel ADD *!*@freenode/staff/* +Aiotv

  9. /query ChanServ ACCESS #channel ADD <bot NickServ account or hostmask> +V

Configure Imgur Image Upload (IIU)

By default, TeleIRC uploads images sent to the Telegram group to Imgur. Since IRC does not support images, Imgur is an intermediary approach to sending pictures sent on Telegram over to IRC. Note that images will be publicly visible on the Internet if the URL is known. See context for why Imgur is enabled by default.

By default, TeleIRC uses the TeleIRC-registered Imgur API key. We highly recommend registering your own API key in high-traffic channels.

To register your own Imgur API key, follow these steps:

  1. Create an Imgur account

  2. Register your bot with Imgur API (select OAuth2 without callback option)

  3. Add provided Imgur client ID to .env file

Deployment Guide

There are two ways to deploy TeleIRC persistently:

  1. Run Go binary

  2. Run TeleIRC in a container

Run binary

This section explains how to configure and install TeleIRC as a simple executable binary.

NOTE: This assumes you are building from source. If you use a pre-built binary from a GitHub Release, skip to Configuration.

Pre-requirements

  • git

  • go (v1.14 and v1.15 supported)

Packages for these pre-requirements are available on most *NIX distributions. Check your distribution documentation for more info on how to install these packages.

Build TeleIRC

This section is only required if you are building a binary from source:

  1. Clone repository (git clone https://github.com/RITlug/teleirc.git)

  2. Enter repository (cd teleirc/)

  3. Build binary (./build_binary.sh)

Configuration

TeleIRC uses godotenv to manage API keys and settings. The config file 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.

See Config file glossary for detailed information.

Start bot

NOTE: This section is one opinionated way to start and configure TeleIRC. Experienced system administrators may have other preferences and slight deviation is permittable. However upstream only offers free support for installations that follow our documentation.

To start the bot, you need to consider the following factors:

  1. Where will the binary go?

  2. Where is your config file on the system?

  3. How will you automate the bot to start-up automatically after a system reboot?

Example Linux setup

NOTE: Looking for an easier way? Check out the TeleIRC Ansible Role for an automated installation of the following steps.

Upstream offers a systemd unit file to automate TeleIRC on a Linux system that uses systemd. This example uses the upstream systemd unit file to automatically run TeleIRC on a Linux system.

This example was tested on a CentOS 8 system and is easily adaptable for other *NIX distributions. It uses v2.2.1 as a default:

# Download TeleIRC deployment assets from GitHub.
$ curl --location --output ~/teleirc https://github.com/RITlug/teleirc/releases/download/v2.2.1/teleirc-2.2.1-linux-x86_64
$ curl --location --output ~/teleirc.sysusers https://raw.githubusercontent.com/RITlug/teleirc/v2.2.1/deployments/systemd/teleirc.sysusers
$ curl --location --output ~/teleirc.tmpfiles https://raw.githubusercontent.com/RITlug/teleirc/v2.2.1/deployments/systemd/teleirc.tmpfiles
$ curl --location --output ~/teleirc@.service https://raw.githubusercontent.com/RITlug/teleirc/v2.2.1/deployments/systemd/teleirc@.service
$ curl --location --output ~/teleirc.env https://raw.githubusercontent.com/RITlug/teleirc/v2.2.1/env.example

# Install TeleIRC files and user
$ sudo install -Dm755 -o root -g root ~/teleirc /usr/local/bin/teleirc
$ sudo install -Dm644 -o root -g root ~/teleirc.sysusers /etc/sysusers.d/teleirc.conf
$ sudo install -Dm644 -o root -g root ~/teleirc.tmpfiles /etc/tmpfiles.d/teleirc.conf
$ sudo install -Dm644 -o root -g root ~/teleirc@.service /etc/systemd/system/teleirc@.service
$ sudo systemd-sysusers /etc/sysusers.d/teleirc.conf
$ sudo systemd-tmpfiles --create /etc/tmpfiles.d/teleirc.conf
$ sudo install -Dm644 -o root -g root ~/teleirc.env /etc/teleirc/example
$ rm ~/teleirc ~/teleirc.sysusers ~/teleirc.tmpfiles ~/teleirc@.service ~/teleirc.env

# Systems with SELinux ONLY.
$ sudo chcon --type bin_t --user system_u /usr/local/bin/teleirc
$ sudo chcon --type etc_t --user system_u -R /etc/teleirc/
$ sudo chcon --type etc_t --user system_u /etc/sysusers.d/teleirc.conf
$ sudo chcon --type etc_t --user system_u /etc/tmpfiles.d/teleirc.conf
$ sudo chcon --type systemd_unit_file_t --user system_u /etc/systemd/system/teleirc@.service

# Start and enable TeleIRC.
$ sudo systemctl enable --now teleirc@example.service

To run multiple instances, create other files in /etc/teleirc/ and enable the service named teleirc@FILENAME.service.

Run container

Containers are another way to deploy TeleIRC. Dockerfiles and other deployment resources are available in deployments/.

NOTE: At time of v2.0.0 release, a container image is available, but mostly untested. Feeling bold and adventurous? Take our Dockerfile for a spin and let us know on GitHub how it works for you.

Download Dockerfile (beta)