README

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.

Two authentication methods are supported:

login/password,
personnal access token.

The second one is necessary if the Mattermost server delegates the authentication to another service (for example when using Mattermost shiped with GitLab). Such method is also probably prefered as the token does not reveals original credentials and can be revoked without any impact on the related account.

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.4.4 of the client. Example:

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

Try the Hubot demo

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

Create an account on the Mattermost nightly builds server at https://pre-release.mattermost.com/
Join the "Hubot" channel
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.

Usage no npm install needed!