Skip to content

Latest commit

 

History

History
255 lines (182 loc) · 12.5 KB

README.md

File metadata and controls

255 lines (182 loc) · 12.5 KB
Raw

nxs-support-bot

nxs-support-bot lets you interact with your task tracker (at present supported Redmine only) via Telegram.

Introduction

Features

  • Get in Telegram messages when issue is created or updated in Redmine
  • Select only interesting issues you wish to follow
  • Answer to Redmine issues by the replying to message in Telegram chat
  • Create new issues in your Redmine using Telegram. Select a project and priority you need for a new issue
  • Operate with files and media
  • Feedback project to communicate with unauthorized users and get feedback
  • Fully localizable interface in appropriate with user selected language
  • Compatible with Redmine 4.2 and 5.0

Who use this tool

Any teams who use Redmine to interact with other team members and customers:

  • Developers
  • Support
  • Sales
  • Marketing
  • etc...

Quickstart

Install

There are two ways described below to install the Bot into your infrastructure.

First you need to do is to clone the repo and go to .deploy/docker-compose or .deploy/kubernetes directory in accordance to the way you choose to install:

git clone git@github.com:nixys/nxs-support-bot.git

Modify the docker-compose.yml or kubernetes manifests according to your infrastructure to make sure you have configured MySQL and Redis before setting up the Bot.

Docker-compose

Do the following steps:

  • Configure nxs-support-bot (see Configure section for details)
  • Launch the Bot with command: 
    docker-compose up -d

Kubernetes

Do the following steps:

  • Install nxs-universal-chart (Helm 3 is required): 
    helm repo add nixys https://registry.nixys.ru/chartrepo/public
  • Configure nxs-support-bot (see Configure section for details)
  • Launch the Bot with command: 
    helm -n nxs-support-bot install nxs-support-bot nixys/universal-chart -f values.yaml

Settings

Default configuration file path: /nxs-support-bot.conf. File represented in yaml.

General settings

Option Type Required Default value Description
logfile String No stdout Log file path. Also you may use stdout and stderr
loglevel String No info Log level. Available values: debug, warn, error and info
pidfile String No - Pid file path. If pidfile is not set it will not be created
api API Yes - API settings
telegram Telegram Yes - Telegram settings
redmine Redmine Yes - Redmine settings
mysql MySQL Yes - MySQL settings
redis Redis No - Redis settings
localization Localization No - Localization settings
cache Cache No - Cache settings
API settings
Option Type Required Default value Description
bind String No 0.0.0.0:80 Address (with port) the bot will listen for a connections from Redmine with an issue updates
tls API TLS No - TLS settings for an Bot API
clientMaxBodySize String No 36m Max body size for a requests from Redmine
secretToken String Yes - This value used to authorize your Redmine in Bot API. You may use any generator of random strings you want to create a secret token
API TLS settings
Option Type Required Default value Description
certfile String Yes - TLS certificate file path
keyfile String Yes - TLS key file path
Telegram settings

Note that the Bot uses the getUpdates method to receive an updates so you only need one option to configure to connect with the Telegram.

Option Type Required Default value Description
apiToken String Yes - Telegram API token for your bot
Redmine settings
Option Type Required Default value Description
host String Yes - Redmine host to connect (e.g.: https://your.redmine.org)
key String Yes - Redmine API key for account with admin permissions. This account is used to get necessary data (such as accounts, projects, priorities, etc) from Redmine
feedback Feedback No - Settings to enable feedback mode in Support bot. Disabled if this setting is not set
Feedback settings

Feedback is used to communicate with users unauthorized in your Redmine. Also useful as a feedback form for customers.

If this module is enabled every user who doesn't have account in your Redmine may write a message to bot. This messages will either create a new issue in specified project in Redmine or add a comment. All your messages in that issues (exclude private comments) will be sent to user via Telegram.

Option Type Required Default value Description
projectIdentifier String Yes - Identifier of the project where feedback issues will be created
userID Int Yes - ID of user a messages will be created from in feedback issues
MySQL settings
Option Type Required Default value Description
host String No 127.0.0.1 Host to connect
port Int No 3306 Port to connect
db String Yes - DB name to connect
user String Yes - User to connect
password String Yes - Password to connect
Redis settings
Option Type Required Default value Description
host String No 127.0.0.1 Host to connect
port Int No 6379 Port to connect
Localization settings
Option Type Required Default value Description
path String No /localization Path to directory with localization files
Cache settings
Option Type Required Default value Description
ttl String No 5m Redmine data cache TTL

Configure

To complete the Bot installation you need to do some actions described in this section.

Redmine

After you've installed and configured the Redmine, do the following to take the nxs-support-bot collaboration.

General

Check the option Enable REST web service on /settings?tab=api page in your Redmine is enabled.

Then create a new one (or take an existing) account with administrator permissions. In the account settings page look for an API access key and use this value as a key option in Redmine settings section.

Feedback project

If you want to have an ability to use Feedback issues in your Bot do the following.

First create a new one (or take an existing) project to store that issues. Take an identifier of this project and use this value as a projectIdentifier option in Redmine feedback settings section.

Last you need to do is to create a new one (or take an existing) feedback account with no administrator permissions and use its ID as an userID option in Redmine feedback settings section.

nxs-chat-redmine plugin

Install and configure nxs-chat-redmine plugin in your Redmine.

Choose the version in accordance with compatibility table:

nxs-support-bot nxs-chat-redmine
v1.0.0 - v1.2.0 v1.5 - v3.2.0
v1.3.0 v4.0.0
v1.4.0 v4.1.0

nxs-support-bot

Now you need to set up nxs-support-bot config file (see options description in settings section). To configure the Bot you need to change the file located according to the way you choose to install:

  • For Docker Compose: file .deploy/docker-compose/.env
  • For Kubernetes: file .deploy/kubernetes/values.yaml, secret nxs-support-bot-env and configmap nxs-support-bot-config

If you didn't use nxs-chat-srv skip this section and back to installation in accordance with method you selected (either Docker-compose or Kubernetes).

Otherwise you need to migrate your old data to new version of Bot with nxs-support-bot-migrate. See the section below for details.

Update from nxs-chat-srv

Only for users of old version

Choose the way for your installation method.

Docker Compose

Do the following steps:

  • Fill the .deploy/docker-compose/.env_migration file with settings to connect to nxs-chat-srv databases (MySQL and Redis). See nxs-support-bot-migrate settings section for details
  • Stop the nxs-chat-srv
  • Start the data migration process from .deploy/docker-compose directory: 
    docker compose -f docker-compose-migrate.yml up -d
  • After process is completed make sure the nxs-support-bot successfully started
  • Stop and delete the data for migration process: 
    docker compose -f docker-compose-migrate.yml down
rm docker-compose-migrate.yml .env_migrate

Go back to the Docker-compose and follow the instructions to complete the nxs-support-bot installation.

Kubernetes

Do the following steps:

  • Fill the .deploy/kubernetes/migrate_values.yaml file with settings to connect to nxs-chat-srv databases (MySQL and Redis) and nxs-support-bot database (MySQL). See nxs-support-bot-migrate settings section for details
  • Stop the nxs-chat-srv
  • Start the data migration process from .deploy/kubernetes directory: 
    helm -n nxs-support-bot install migrate nixys/universal-chart -f migrate_values.yaml
  • Wait for job nxs-support-bot-migrate been completed
  • Uninstall migration job: 
    helm -n nxs-support-bot uninstall migrate

Go back to the Kubernetes and follow the instructions to complete the nxs-support-bot installation.

Roadmap

Following features are already in backlog for our development team and will be released soon:

  • Notifications to the mention users
  • Default language in accordance with Telegram lang settings for user accounts
  • Ability to specify trackers and other options for new issues
  • Ability to follow/unfollow to an issue from Telegram
  • PgSQL support

Feedback

For support and feedback please contact me:

License

nxs-support-bot is released under the Apache License 2.0.