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¶
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:
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:
Optional BotFather tweaks¶
Set a description or add profile picture for your bot
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:
High-level overview of how to set up your IRC channel
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:
/join #channel
/query ChanServ REGISTER #channel
/query ChanServ SET #channel GUARD on
/query ChanServ ACCESS #channel ADD <NickServ account> +AORfiorstv
(repeat for each IRC user who needs admin access) (what do these mean?)/query ChanServ SET mlock #channel +Ccnt
/mode #channel +q $~a
/query ChanServ ACCESS #channel ADD *!*@gateway/* +V
/query ChanServ ACCESS #channel ADD *!*@freenode/staff/* +Aiotv
/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:
Create an Imgur account
Register your bot with Imgur API (select OAuth2 without callback option)
Add provided Imgur client ID to
.env
file
Deployment Guide¶
There are two ways to deploy TeleIRC persistently:
Run Go binary
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:
Clone repository (
git clone https://github.com/RITlug/teleirc.git
)Enter repository (
cd teleirc/
)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:
Where will the binary go?
Where is your config file on the system?
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.