Create a new Teleirc bridge

This guide explains how to create a new Teleirc bridge. It explains updating the Ansible project, opening a pull request, and pushing changes to production.

Acquire Vault passphrase

For SIG members only.

Telegram secrets (e.g. API tokens and chat IDs) are stored in an encrypted file. A passphrase is required to decrypt the Ansible Vault file with the Telegram secrets.

Set up Ansible Vault on your workstation with these steps:

  1. Install Ansible: sudo dnf install ansible

  2. Request Ansible Vault passphrase from SIG sponsor [1].

  3. Insert plain-text passphrase in this file: ~/.config/ansible/teleirc_ansible_vault_pass

  4. Change file permissions to prevent unauthorized access: (chmod 600 ~/.config/ansible/teleirc_ansible_vault_pass)

  5. Open secrets file: ansible-vault edit roles/teleirc/vars/vault.yml [2]

Add self to authorized_users

For SIG members only.

Add your system user on the Teleirc host machine to the Teleirc admin group. Authorized users are listed at roles/teleirc/vars/main.yml. Add a new line to the list with your FAS username to grant access.

If you cannot log in with your FAS [3] account, contact a sponsor for help.

Add new bot in main.yml variable file

Add a new bot by adding a section to roles/teleirc/vars/main.yml. Bots are sorted alphabetically. Please preserve this sort order.

Use the following excerpt as a template for a new bot:

bots:
  fedora_TEAMNAME: (1)
    cn: "fedora-TEAMNAME" (2)
    irc_blacklist: "" (3)
    irc_bot_name: fzh-tg
    irc_channel: "#fedora-zh"
    irc_server: "{{ default_irc_server }}" (4)
    irc_nickserv_service: "{{ default_irc_nickserv_service }}"
    irc_nickserv_password: "{{ vault_bots.fedora_TEAMNAME.vault_irc_nickserv_password }}"
    teleirc_token: "{{ vault_bots.fedora_TEAMNAME.vault_teleirc_token }}"
    teleirc_chat_id: "{{ vault_bots.fedora_TEAMNAME.vault_teleirc_chat_id }}"
    imgur_client_id: "{{ default_imgur_client_id }}"
    version: "{{ default_version }}"
1 Change TEAMNAME to a lower-case team, SIG, or sub-project name
2 "cn" means common name. Used for directories and systemd unit files.
3 Ignore specific IRC nicks. Messages from these nicks will not go to Telegram (helpful for fedmsg bots).
4 Defaults to Freenode. Defaults placed at top of roles/teleirc/vars/main.yml.

Add new bot secrets in vault.yml variable file

For SIG members only.

Finally, add Telegram secrets to finish configuration. The requesting person is instructed to provide the Telegram secrets. SIG members are not expected to create the Telegram bot unless absolutely necessary.

Edit the secrets file from the root directory of the repo:

ansible-vault edit roles/teleirc/vars/vault.yml

Add provided Telegram secrets in the following format. Note this list is also sorted alphabetically:

vault_bots:
  fedora_TEAMNAME:
    vault_irc_nickserv_password: "" (1)
    vault_teleirc_token: "00000:0000000000" (2)
    vault_teleirc_chat_id: "-000000000" (3)
1 NickServ account password. Not currently used.
2 API token from a Telegram bot. Provided by requestee.
3 Chat ID of a specific Telegram group. Provided by requestee. See how to get the chat ID here.

Open pull request

Verify your changes are correct. Open a pull request and request peer review on your pull request. Request review by asking in the Fedora CommOps channel / group.

Push changes via playbook

For SIG members only.

Once your pull request is reviewed, push changes to production with the Ansible playbook:

ansible-playbook -K playbooks/telegram-irc.yml

The -K flag prompts for a sudo password on the host. If authorized, this is likely your FAS password.

Once the playbook finishes, the bot is deployed. It automatically starts at the end of the playbook run. Test both sides of the bridge are operational.

Congrats! You’re done!

1. The passphrase is sent via GPG-encrypted email or a Telegram Secret Chat. Find out who is a sponsor by checking this list.
2. You must be in the root directory of the project, with ansible.cfg, for Ansible Vault to work automatically.
3. FAS: Fedora Account System