hubot-matteruser

Hubot is "chat bot" created by GitHub that listens for commands and executes actions based on your requests.

hubot-matteruser is a Hubot adapter for Mattermost written in coffee script that uses the Mattermost Web Services API and WebSockets to deliver Hubot functionality.

• Learn more about Hubot in Wired Magazine
• Learn more about Mattermost as an open source, self-hosted team communication server

Description

This Hubot adapter connects to your Mattermost server. You can invite your bot to any channel just as a regular user. It listens and perform your commands. The adapter uses mattermost-client for all low level Mattermost communication.

Try the Hubot demo

You can try out Hubot by joining the Mattermost community server and joining the Hubot channel:

1. Create an account on the Mattermost nightly builds server at https://pre-release.mattermost.com/
2. Join the "Hubot" channel
3. Type hubot help for instructions

Sample commands

You can try a simple command like hubot the rules to bring some static text stored in Hubot:

Try hubot animate me to have Hubot reach out to Giphy and bring back a random animated image.

Try hubot map me [NAME_OF_CITY] to have Hubot reach out to Google Maps and bring back a map based on the name of a city you pass in as a parameter. For example, hubot map me palo alto brings back the below map of Palo Alto

Docker usage

Standalone

Clone this repository, then build the Hubot-Matteruser container:

docker build --build-arg hubot_owner=<owner> \
             --build-arg hubot_name=<name> \
             --build-arg hubot_description=<desc> \
             --tag=hubot-matteruser \
             .

Start the container:

docker run -it \
           --env MATTERMOST_HOST=<mm_host> \
           --env MATTERMOST_GROUP=<mm_team> \
           --env MATTERMOST_USER=<mm_user_email> \
           --env MATTERMOST_PASSWORD=<mm_user_password> \
           -p 8080:8080 \
           --name hubot-matteruser \
           hubot-matteruser

Docker Compose

To integrate with a running Mattermost instance, update docker-compose.yml accordingly and launch the bot:

docker-compose build
docker-compose run -d

If you just want to test locally, you can find here a fork of the official Mattermost Docker Compose stack plugged to Hubot-Matteruser:

Installation

1) Install a Mattermost server

Follow the Mattermost install guides to set up the latest version of Mattermost 4.4.x.

IMPORTANT: Make sure your hubot-matteruser and mattermost-client versions match the major version of your Mattermost server so the API versions will match.

For example, if you're using Mattermost server version 4.4.0 the major version is "4.4", and it is highly recommended to use version 4.4.x of hubot-matteruser and mattermost-client. See releases archive for older versions.

2) Install hubot-matteruser

On a separate server, install hubot-matteruser using the following commands:

npm install -g yo generator-hubot
yo hubot --adapter matteruser

Follow the instructions to set up your bot, including setup of mattermost-client.

Environment variables

The adapter requires the following environment variables to be defined before your Hubot instance will start:

| Variable | Required | Description | |----------|----------|-------------| | MATTERMOST_HOST | Yes | The Mattermost host e.g. mm.yourcompany.com | | MATTERMOST_GROUP | Yes | The team/group on your Mattermost server e.g. core | | MATTERMOST_USER | Yes | The Mattermost user account name e.g. [email protected] | | MATTERMOST_PASSWORD | Yes | The password of the user e.g. s3cr3tP@ssw0rd! | | MATTERMOST_WSS_PORT | No | Overrides the default port 443 for websocket (wss://) connections | | MATTERMOST_HTTP_PORT | No | Overrides the default port (80 or 443) for http:// or https:// connections | | MATTERMOST_TLS_VERIFY | No | (default: true) set to 'false' to allow connections when certs can not be verified (ex: self-signed, internal CA, ... - MITM risks) | | MATTERMOST_USE_TLS | No | (default: true) set to 'false' to switch to http/ws protocols | | MATTERMOST_LOG_LEVEL | No | (default: info) set log level (also: debug, ...) | | MATTERMOST_REPLY | No | (default: true) set to 'false' to stop posting reply responses as comments | | MATTERMOST_IGNORE_USERS | No | (default: empty) Enter a comma-separated list of user senderi_names to ignore. |

Example configuration

The below example assumes you have created a user [email protected] with username hubot and password s3cr3tP@ssw0rd! on your Mattermost server in the core team reachable on URL https://mm.yourcompany.com/core

export MATTERMOST_HOST=mm.yourcompany.com 
export MATTERMOST_GROUP=core
export [email protected]
export MATTERMOST_PASSWORD=s3cr3tP@ssw0rd!

Upgrade

To upgrade your Hubot for Mattermost 4.4.x, find the package.json file in your Hubot directory and look for the line in the dependencies section that references hubot-matteruser. Change the verion so it points to ^4.4.0 of the client. Example:

  ...
  "dependencies": {
    "hubot-matteruser": "^4.4.0"
  },
  ...

License

The MIT License. See LICENSE file.