The Absolute Fastest Way to Get Started with Mattermost Apps

October 19, 2021

Platform

This post outlines the quickest path available for a developer to use a basic Mattermost app on a local setup. It makes use of Docker containers, a Node.js app, and — of course — a Mattermost instance!

When you’re ready to get started with the Mattermost App Framework, here are the steps that you will need to take.

Clone the following GitHub repo

git clone https://github.com/mattermost/mattermost-plugin-apps.git

Once that’s done, change the directory to the dev folder.

There should be a folder named node_app, a docker-compose.yml file and a couple of other files (used for housekeeping).

cd dev
ls -la

Get Started with Mattermost Apps Image 1

Run the Docker compose file to spin up the containers

docker-compose up

The following output on your terminal will indicate a successful run:

Getting Started with Mattermost Apps Image 2

Internally, this command spins up three containers:

A Mattermost server
A Postgres database
A Node.js app

Access the Mattermost instance in the browser

Navigate to https://localhost:8065 to access your Mattermost instance. Complete the presented steps to finish setting it up.

Install the test app

In the default channel, install the node_app test app using the following command:

/apps install http https://node_app:4000/manifest.json

Paste the above install command into the input chat box at the bottom of the browser. This will bring up a dialog.

Complete the installation by clicking the Submit button. Once installed, you will receive a system-generated confirmation message from appsbot.

Test the installation

Next, test this installation by typing in the following slash command:

/node-example send test-message

This will send a message to you from the bot via DM. You can also test the same function using the button on the channel header, which will open a modal asking for your input.

Potential errors and troubleshooting information

Here’s a list of common errors you may encounter while working through the steps listed above. Depending on your starting point, configuration, and other steps, you may run into one or more of them.

Keep reading to learn the most common errors and the solutions that will help you quickly resolve each of them and move through the steps very quickly.

docker command not found

If you come across this error, it means that you have not installed Docker on your machine. The solution to this problem is simple: Install Docker.

Please use these instructions to install Docker on your machine and retry the command.

If you’ve already installed Docker, the command may not be available on your current path. To solve this, add it to your $PATH variable.

Cannot find module 'mattermost-redux/client/client4'

This error — which signifies missing dependencies for the app to be able to build/run — occurs when the Node.js application is running. To resolve this issue, navigate to the node_modules folder in the dev environment. Switch into the mattermost-redux directory and run the npm install command.

Once that’s done, run the command to spin up the container for the Node.js app again.

Slash command failure

You may come across an error when executing the slash command from the Mattermost interface. Should this happen, the following error message will be displayed in red:

Failed to create/fetch DM channel: Invalid or expired session, please login again.

This error message will correspond to this log entry:

mattermost_1  | {"level":"debug","ts":1632910234.8690574,"caller":"mlog/sugar.go:17","msg":"Received call response","plugin_id":"com.mattermost.apps","app_id":"node-example","acting_user_id":"xgzbjbdiktdhbk38ycnpikn3hh","error":"Failed to create/fetch DM channel: Invalid or expired session, please login again.","type":"error","path":"/send/submit"}

This error represents a misconfiguration in the database and means that the app configuration will not be read correctly by the Mattermost instance. The only way to solve this is to purge the containers and create them again.

Run the docker ps command with the a flag. The output will contain details about three containers that pertain to the present Mattermost instance. They are:

$ docker ps -a

CONTAINER ID	IMAGE	COMMAND	CREATED	STATUS	PORTS	NAMES
4916720885c4	node:13	“docker-entrypoint.s…”	4 days ago	Exited (0) 45 minutes ago		dev_node_app_1
78818e3118d3	mattermost/mattermost-enterprise-edition:master.227937	“/entrypoint.sh matt…”	4 days ago	Exited (0) 45 minutes ago		dev_mattermost_1
3063883fc4f4	postgres	“docker-entrypoint.s…”	4 days ago	Exited (0) 45 minutes ago		dev_db_1

Using the Container ID available in the first column, delete the three containers using the following command:

$docker rm -rf

Run the command to spin up the containers once again and reinstall the Mattermost app to restore it. This will wipe out all the corrupt data from before and will function as a fresh installation.

$docker-compose up

Get started with the Mattermost Apps Framework

This post covers the quickest way to get started with the Mattermost Apps Framework. You can do a lot more with it by connecting it to applications that are part of your workflow.

To continue your learning, find out how to connect to apps written in JavaScript or Golang using quickstart guides. You can also make use of the Mattermost Development Guide to explore all the integrations that are available. Additionally, you can browse a gallery of all the integrations in the Marketplace to check out the various ways in which the community is helping extend the core of Mattermost to fit with different needs.

If you would like help or support, please make use of the Mattermost Community server—specifically the channel for Apps. There, you can hop in on the conversation about building, testing, and using the apps you’re building.