Mattermost Logo
Edit on GitHub

Quick Start

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

Building 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/mattermost-server

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/plugin"
)

type HelloWorldPlugin struct {
	plugin.MattermostPlugin
}

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

Note: Your executable is platform specific! If you’re building the plugin for a server running on a different operating system, you’ll need to use a slightly different command. For example, if you’re developing the plugin from MacOS and deploying to a Linux server, you’ll need to use this command:

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-sample for helpful build scripts.

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

id: com.mattermost.server-hello-world
name: Server "Hello, world!"
server:
    executable: plugin.exe

This manifest gives the server the location of our executable within our bundle. (Note that you may alternatively use plugin.json, as shown in webapp/hello-world/.) Consult the manifest reference for more details, including how to define a cross-platform bundle by defining multiple executables.

Bundle the manifest and executable into a tar file:

tar -czvf plugin.tar.gz plugin.exe plugin.yaml

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

Installing 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 (Beta) > 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.yaml``, 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.yaml
            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.