make commands for working with plugins make test - Runs the plugin’s server tests and webapp testsmake check-style - Runs linting checks on the plugin’s server and webapp foldersmake deploy - Compiles the plugin using the make dist command, then automatically deploys the plugin to the Mattermost server. Enabling Local Mode on your server is the easiest way to use this command.make watch - Uses webpack’s watch feature to re-compile and deploy the webapp portion of your plugin on any change to the webapp/src folder.make dist - Compile the plugin into a g-zipped file, ready to upload to a Mattermost server. The file is saved in the plugin repo’s dist folder.make enable - Enables the plugin on the Mattermost servermake disable - Disables the plugin on the Mattermost server.make reset - Disables and re-enables the plugin on the Mattermost server.make attach-headless - Starts a delve process and attaches it to your running plugin.make clean - Force deletes the content of build-related files. Use when running into build issues.You can run the development build of the plugin by setting the environment variable MM_DEBUG=1, or prefixing the variable at the beginning of the make command. For example, MM_DEBUG=1 make deploy will deploy the development build of the plugin to your server, allowing you to have a more fluid debugging experience. To use the production build of the plugin instead, unset the MM_DEBUG environment variable before running the make commands.
In order for your IDE to know the root directory of the plugin’s webapp code, it is advantageous to open the IDE in the webapp folder itself when working on the webapp portion of the plugin. This way, the IDE is aware of files such as webpack.config.js and tsconfig.json.
ngrok When a plugin integrates with an external service, webhooks and/or authentication redirects are necessary, which requires your local server to be available on the web. In order for your Mattermost server to be available to process webhook requests, it needs to expose its port to an external address. A common way to do this is to use the command line tool ngrok. Follow these steps to set up ngrok with your server:
PATH.ngrok http 8065 to make your Mattermost server available for webhook requests.https URL from the ngrok command’s output, and log into Mattermost.https address given from the ngrok command output.If you’re using a free ngrok account, the URL given by the output of the ngrok http command will be different each time you run the command. As a result, you’ll need to adjust the webhook URL on Mattermost’s side and the external service’s side (e.g. GitHub) each time you run the command.
With this setup, many integrations require you to be logged into Mattermost using your ngrok URL. After logging into your ngrok URL pointed to your Mattermost server, in most cases you can continue using your localhost address in your browser for quicker network requests to your server. If you receive an error like unauthorized or enable third-party cookies when connecting to an external service, make sure you’re logged into your ngrok URL in the same browser.
localhost.run instead of ngrok If you would like to avoid using ngrok, there is another free option that you can run from your terminal, called localhost.run. Use this command to expose your server:
ssh -R 80:localhost:8065 ssh.localhost.run
An http URL pointing to your server should show in the terminal. The https version of this same URL should also work, which is what you will want to use for your webhook URLs. One disadvantage of using localhost.run is there is no request/response logging dashboard that is available with ngrok.
delve Using the delve debugger, we can step through code for a running plugin on our local Mattermost server. There are a few steps for setup to make this work properly.
In order to allow the debugger to pause code execution, we need to disable Mattermost’s “health check” for plugins and the Hashicorp go-plugin package’s “keep alive” feature for its RPC connection. We’ll configure the server with the following steps:
config.json, set PluginSettings.EnableHealthCheck to false./patch_go_plugin.sh $GO_PLUGIN_PACKAGE_VERSION where GO_PLUGIN_PACKAGE_VERSION is the version of go-plugin that your Mattermost server is using. This can be found in the monorepo at server/go.mod on your local server.More details on this are explained below:
To disable the Mattermost plugin health check job, go into your config.json and set PluginSettings.EnableHealthCheck to false. Note that this will make it so if your plugin panics/crashes for any reason during your development, the Mattermost server will not restart the plugin or notice that it crashed. It will remain with the status of “running” in the plugin management page, even though it has crashed. Because of this, you’ll need to watch server logs for any information related to plugin panics during your debugging.
go-plugin RPC client “keep alive” We’ll be editing external library source code directly, so we only want to do this in a development environment.
By default, the go-plugin package runs plugins with a “keep alive” feature enabled, which essentially pings the plugin RPC connection every 30 seconds, and if the plugin doesn’t respond, the RPC connection will be terminated. There is a way to disable this, though the go-plugin currently doesn’t expose a way to configure this setting, so we need to edit the go-plugin package’s source code to have the right configuration for our debugging use case.
In the script below, we automatically modify the file located at ${GOPATH}/pkg/mod/github.com/hashicorp/go-plugin@${GO_PLUGIN_PACKAGE_VERSION}/rpc_client.go, where GO_PLUGIN_PACKAGE_VERSION is the version of go-plugin that your Mattermost server is using. This can be found in your local copy of the monorepo at server/go.mod. This script essentially replaces the line in go-plugin/rpc_client.go to have a custom configuration for the RPC client connection, that disables the “keep alive” feature. This makes it so the debugger can be paused for long amounts of time, and the Mattermost server will keep the connection with the plugin open.
# patch_go_plugin.sh
GO_PLUGIN_PACKAGE_VERSION=$1
GO_PLUGIN_RPC_CLIENT_PATH=${GOPATH}/pkg/mod/github.com/hashicorp/go-plugin@${GO_PLUGIN_PACKAGE_VERSION}/rpc_client.go
echo "Patching $GO_PLUGIN_RPC_CLIENT_PATH for debugging Mattermost plugins"
if ! grep -q 'mux, err := yamux.Client(conn, nil)' "$GO_PLUGIN_RPC_CLIENT_PATH"; then
echo "The file has already been patched or the target line was not found."
exit 0
fi
sudo sudo sed -i '' '/import (/a\
"time"
' $GO_PLUGIN_RPC_CLIENT_PATH
sudo sed -i '' '/mux, err := yamux.Client(conn, nil)/c\
sessionConfig := yamux.DefaultConfig()\
sessionConfig.EnableKeepAlive = false\
sessionConfig.ConnectionWriteTimeout = time.Minute * 5\
mux, err := yamux.Client(conn, sessionConfig)
' $GO_PLUGIN_RPC_CLIENT_PATH
echo "Patched go-plugin's rpc_client.go for debugging Mattermost plugins"
Then run the script like so:
chmod +x patch_go_plugin.sh
./patch_go_plugin.sh v1.6.0 # as of writing, this is the version of `go-plugin` being used by the server
This section assumes you are using VSCode to debug your plugin. If you want to use a different IDE, the process will be mostly the same. If you want to debug in your terminal directly with delve instead of using an IDE, you can run make attach instead of make attach-headless below, which will launch a delve process as an interactive terminal.
Include this configuration in your VSCode instance’s launch.json:
{
"name": "Attach to Mattermost plugin",
"type": "go",
"request": "attach",
"mode": "remote",
"port": 2346,
"host": "127.0.0.1",
"apiVersion": 2
}
delve process to the running plugin Build the plugin and deploy to your local Mattermost server:
make deploy
In a separate terminal, open a delve process for VSCode to connect to:
make attach-headless
This starts a headless delve process for your IDE to connect to. The process listens on port 2346, which is the port defined in our launch.json configuration. Somewhat related, the Mattermost server’s Makefile has a command debug-server-headless, which starts a headless delve process for the Mattermost server, listening on port 2345. So you can create a similar launch.json configuration in the server directory of the monorepo to connect to your server by using that port.
delve process Run the debugger in VSCode by navigating to the “Run and Debug” tab on the left side of the IDE, selecting your launch configuration, and clicking the green play button. This should bring up a debugging widget that looks like this:
Your IDE’s debugger is now running and ready to pause your plugin’s execution at any breakpoints you set in the IDE.
If you run into issues with debugging, first make sure you’ve stopped any active debugging sessions by clicking the red disconnect button in the VSCode debugging widget.
You can then use the make reset command in the plugin repository to do the following:
delve processes running for this pluginFor more discussion on this, please join the Toolkit channel on our community server: https://community.mattermost.com/core/channels/developer-toolkit