Mattermost Plugins on FreeBSD (2021)

Estimated reading time: 3 minutes.

While Mattermost is easily available on FreeBSD, being packaged to build yourself courtesy of FreeBSD Ports as well as available as a binary courtesy of FreeBSD Packages, it's not the same story with the plugins.

Mattermost has a "Plugin Marketplace" which allows you to download and install plugins in a single click, but nearly all of these will fail to enable after install. The reason for this is generally because these plugins are provided as compiled binaries, and only contain binaries for Linux, OSX, and Windows. No FreeBSD!

Thankfully, most plugins require only minimal changes in order to make them usable under FreeBSD. These changes can be applied successfully to the plugin "starter template" provided by Mattermost themselves which most plugins are based off of, so there's a high chance of success with most plugins.

Use the Source

We need to compile the plugin ourselves, so the first thing you need to do is find the source to the plugin. Many Mattermost plugins are available on Github. A couple I find useful:

Do a review of the plugins build instructions to catch any required dependencies, build tools, etc. You will almost definitely the go, golangci-lint, gmake and npm packages (and their required dependencies) which are all available through FreeBSD's ports and packages systems. A simple pkg install go golangci-lint gmake npm should get you started.

Make the Necessary Changes

There are two simple changes that most plugins will require.

In the Makefile, modify the follow block as indicated:

ifneq ($(HAS_SERVER),)
	mkdir -p server/dist;
	cd server && env GOOS=linux GOARCH=amd64 $(GO) build $(GO_BUILD_FLAGS) -o dist/plugin-linux-amd64;
	cd server && env GOOS=darwin GOARCH=amd64 $(GO) build $(GO_BUILD_FLAGS) -o dist/plugin-darwin-amd64;
	cd server && env GOOS=windows GOARCH=amd64 $(GO) build $(GO_BUILD_FLAGS) -o dist/plugin-windows-amd64.exe;
	# Add the below line
	cd server && env GOOS=freebsd GOARCH=amd64 $(GO) build $(GO_BUILD_FLAGS) -o dist/plugin-freebsd-amd64;
endif

If the block above differs from what's present in the Makefile, basically just duplicate the existing Linux build line adjusting the GOOS environment variable and the output path specified by -o.

Unfortunately, the plugin.json file does not support explicitly specifying an executable for use on FreeBSD. However, a legacy field provides an easy workaround. Modify as follows:

    "server": {
        "executables": {
            "linux-amd64": "server/dist/plugin-linux-amd64",
            "darwin-amd64": "server/dist/plugin-darwin-amd64",
            "windows-amd64": "server/dist/plugin-windows-amd64.exe"
        },
        // Add the below line
        "executable": "server/dist/plugin-freebsd-amd64"
    },

Build the Plugin

In the plugin folder, try running gmake and see what happens!

If all goes well, the dist/ folder will contain a .tar.gz package containing the binaries and other resources the plugin depends on.

Install the Plugin

There is an option that can be enabled to install the plugin through the Mattermost administrator interface, but there's a simpler option especially if you're building the plugin on the same device that's running Mattermost.

Extract the generated archive in your Mattermost plugin directory. If you're using the port/package, the default path is /usr/local/www/mattermost/plugins/. Ensure the permissions are set appropriately (generally, owned by the mattermost user).

Log into your Mattermost administrator interface, navigate to "Plugin Management" and then scroll down to "Installed Plugins". You should be able to Enable the plugin now successfully! (If it fails, check your Mattermost log, default at /usr/local/www/mattermost.log.)

Good luck out there!