Write a Mattermost Plugin

This tutorial will walk you through the basics of writing a Mattermost plugin with a server component.

Note that the steps below are intentionally very manual to explain all of the pieces fitting together. In practice, we recommend referencing mattermost-plugin-starter-template for helpful build scripts. Also, the plugin API changed in Mattermost 5.2. Consult the migration document to upgrade older plugins.

Prerequisites 

Mattermost plugins extend the server using a Go API. In the future, gRPC may be supported, allowing you to write plugins in any language. For now, you’ll need a functioning Go environment, so follow Go's Getting Started guide if needed.

You’ll also need a Mattermost server to install and test the plugin. This server must have Enable set to true in the PluginSettings section of its config file. If you want to upload plugins via the System Console or API, you’ll also need to set EnableUploads to true in the same section.

Build the plugin 

The process that will communicate with the Mattermost server is built using a set of APIs provided by the source code for the Mattermost server.

Download the source code for the Mattermost server:

go get -u github.com/mattermost/server/v8

Define $GOPATH. By default, this is already $HOME/go, but it’s helpful to make this explicit:

export GOPATH=$HOME/go

Now, create a directory to act as your workspace:

mkdir -p $GOPATH/src/my-plugin
cd $GOPATH/src/my-plugin

Create a file named plugin.go with the following contents:

package main

import (
	"fmt"
	"net/http"

	"github.com/mattermost/mattermost/server/public/plugin"
)

// HelloWorldPlugin implements the interface expected by the Mattermost server to communicate
// between the server and plugin processes.
type HelloWorldPlugin struct {
	plugin.MattermostPlugin
}

// ServeHTTP demonstrates a plugin that handles HTTP requests by greeting the world.
func (p *HelloWorldPlugin) ServeHTTP(c *plugin.Context, w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, "Hello, world!")
}

// This example demonstrates a plugin that handles HTTP requests which respond by greeting the
// world.
func main() {
	plugin.ClientMain(&HelloWorldPlugin{})
}

This plugin will register an HTTP handler that will respond with “Hello, world!” when requested.

Build the executable that will be distributed with your plugin:

go build -o plugin.exe plugin.go

GOOS=linux GOARCH=amd64 go build -o plugin.exe plugin.go

Also note that the “.exe” extension is required if you’d like your plugin to run on Windows, but is otherwise optional. Consider referencing mattermost-plugin-starter-template for helpful build scripts.

Now, we’ll need to define the required manifest describing your plugin’s entry point. Create a file named plugin.json with the following contents:

{
    "id": "com.mattermost.server-hello-world",
    "name": "Hello World",
    "server": {
        "executable": "plugin.exe"
    }
}

This manifest gives the server the location of your executable within your plugin bundle. Consult the manifest reference for more details, including how to define a cross-platform bundle by defining multiple executables, and how to define a minimum required server version for your plugin.

Note that you may also use plugin.yaml to define the manifest.

Bundle the manifest and executable into a tar file:

tar -czvf plugin.tar.gz plugin.exe plugin.json

You should now have a file named plugin.tar.gz in your workspace. Congratulations! This is your first server plugin!

Install the plugin 

Install the plugin in one of the following ways:

1. Through System Console UI:

   • Log in to Mattermost as a System Admin.
   • Open the System Console at /admin_console
   • Navigate to Plugins > Plugin Management* and upload the plugin.tar.gz you generated above.
   • Click Enable under the plugin after it has uploaded.

2. Or, manually:

   • Extract plugin.tar.gz to a folder with the same name as the plugin id you specified in plugin.json, in this case com.mattermost.server-hello-world/.

   • Add the plugin to the directory set by PluginSettings > Directory in your config.json file. If none is set, defaults to ./plugins relative to your Mattermost installation directory. The resulting directory structure should look something like:

     mattermost/
         plugins/
             com.mattermost.server-hello-world/
                 plugin.json
                 plugin.exe
     

   • Restart the Mattermost server.

Once you’ve installed the plugin in one of the ways above, browse to https://<your-mattermost-server>/plugins/com.mattermost.server-hello-world, and you’ll be greeted by your plugin.