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 Javascript 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.

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

or if you have a personal access token:

$ docker run -it \
           --env MATTERMOST_HOST=<mm_host> \
           --env MATTERMOST_GROUP=<mm_team> \
           --env MATTERMOST_ACCESS_TOKEN=<personal>
           -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 5.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.

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	No	The Mattermost user account name e.g. hubot@yourcompany.com
MATTERMOST_PASSWORD	No	The password of the user e.g. s3cr3tP@ssw0rd!
MATTERMOST_ACCESS_TOKEN	No	The personal access token of the user
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 hubot@yourcompany.com 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 MATTERMOST_USER=hubot@yourcompany.com
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 ^5.3.0 of the client. Example:

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

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

License

The MIT License. See LICENSE file.