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.
- Create a Telegram bot
- Configure IRC channel
- Deployment Guide
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:
- Create a Telegram bot to obtain a Telegram API token
- Set up an IRC channel for best user experience
- 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.
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 (
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.
- Unauthenticated users may join the channel.
- Only authenticated users may write in the channel (i.e.
- 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:
/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)¶
NOTE: The Imgur Image Upload (IIU) feature is not yet available in v2.x.x releases.
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 generic Imgur API key. Imgur highly recommends registering each bot.
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
There are two ways to deploy TeleIRC persistently:
- Run Go binary
- Run TeleIRC in a container
This section explains how to configure and install TeleIRC as a simple executable binary.
- go (v1.13 and v1.14 supported)
Packages for these pre-requirements are available on most
Check your distribution documentation for more info on how to install these packages.
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 (
- Build binary (
go build cmd/teleirc.go)
TeleIRC uses godotenv to manage API keys and settings.
The config file is a
Copy the example file to a production file to get started (
cp env.example .env).
.env file with your API keys and settings.
See Config file glossary for detailed information.
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.
This example was tested on a CentOS 8 system and is easily adaptable for other
v2.0.0 as a default:
# Change ~/teleirc and ~/teleirc-env with equivalents on your system. # Download TeleIRC deployment assets from GitHub. $ curl --location --output ~/teleirc https://github.com/RITlug/teleirc/releases/download/v2.0.0/teleirc-2.0.0-linux-64bit $ curl --location --output ~/teleirc-env https://raw.githubusercontent.com/RITlug/teleirc/v2.0.0/env.example $ curl --location --output ~/teleirc.service https://raw.githubusercontent.com/RITlug/teleirc/v2.0.0/deployments/systemd/teleirc.service # Harden/fix file permissions. $ chmod 755 ~/teleirc $ chmod 600 ~/teleirc-env $ chmod 644 ~/teleirc.service # Install TeleIRC locally on system. $ sudo chown root:root ~/teleirc* $ mkdir -p /etc/teleirc/ $ sudo mv ~/teleirc /usr/local/bin/teleirc $ sudo mv ~/teleirc-env /etc/teleirc/env $ sudo mv ~/teleirc.service /usr/lib/systemd/system/multi-user.target.wants/teleirc.service # Systems with SELinux ONLY. $ sudo chcon --type bin_t --user system_u /usr/local/bin/teleirc $ sudo chcon --type etc_t --user system_u /etc/teleirc/env $ sudo chcon --type systemd_unit_file_t --user system_u /usr/lib/systemd/system/multi-user.target.wants/teleirc.service # Start and enable TeleIRC. $ sudo systemctl enable --now teleirc.service
Containers are another way to deploy TeleIRC.
Dockerfiles and other deployment resources are available in
At time of v2.0.0 release, a container image is available, but mostly untested.
Feeling bold and adventurous?
Dockerfile for a spin and let us know on GitHub how it works for you.