Set up your development environment for building, running, and testing Mattermost.

iNote

• If you're migrating from before the monorepo see the migration notes.
• If you're developing plugins, see the plugin developer setup documentation.
• If you are forking Mattermost to create a derivative version, you must comply with the AGPLv2 license in both source code and compiled versions and replace the Mattermost name and logo from the system, among other requirements, per the Mattermost trademark policy.

Prerequisites for Windows

If you're using Windows, we recommend using the Windows Subsystem for Linux (WSL) for Mattermost development. Go and Node must be run from within WSL, so you'll need to install them in WSL even if you already have the Windows versions of them installed.

1. Install WSL by running the following command as an administrator in PowerShell: wsl --install
2. Install Docker Desktop for Windows on your Windows machine. Alternatively, you can also install docker engine directly on your linux distribution.
3. Perform the rest of the operations (except Docker installation) within the WSL environment and not in Windows.

Setup the Mattermost Server

iNote

The web app isn't exposed directly, it's exposed via the server. So if both server and web app are running, you can open localhost:8065, the server's port to access the web app.

1. Install make.

   • On Ubuntu, you can install build essential tools which will also take care of installing the make:

     sudo apt install build-essential

2. Install and run Docker. If you don't want to use Docker, you can follow this guide.

   • When running docker commands under WSL2, if you receive the error The command 'docker' could not be found in this WSL 2 distro. you may need to toggle the Use the WSL 2 based engine off and on within Docker Settings after installation.
   • Make sure that Docker has virtual file share access to the directory that you will clone the repository in

3. Install Go.

   • Version 1.21 or higher is required.

4. Increase the number of available file descriptors. Update your shell's initialization script (e.g. .bashrc or .zshrc), and add the following:

   ulimit -n 8096

5. If you don't have it already, install libpng with your preferred package manager.

   • If you are on ARM based Mac, you'll need to install Rosetta to make libpng work. Rosetta can be installed by the following command-

     softwareupdate --install-rosetta

6. Fork https://github.com/mattermost/mattermost.

7. Clone the Mattermost source code from your fork:

   git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost.git

8. Install NVM and use it to install the required version of Node.js:

   1. Install NVM by following these instructions.

   2. Then, use NVM to install the correct version of Node.js for the Mattermost web app (this should be run within the webapp directory):

      nvm install

9. Start the server:

   cd server
   make run-server

10. Test your environment to ensure that the server is running:

    curl http://localhost:8065/api/v4/system/ping

    If successful, the curl step will return a JSON object:

    {"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}

11. Set up up your admin user using mmctl:

    bin/mmctl user create --local --email ADMIN_EMAIL --username ADMIN_USERNAME --password ADMIN_PASSWORD --system-admin

    • Optionally, you can also populate the database with random sample data as well:

      bin/mmctl sampledata

12. Start the web app:

    cd webapp
    make run

13. Open the web app by going to http://localhost:8065 in your browser or by adding it to the Mattermost desktop app.

14. Stop the server:

    make stop-server

    The stop-server make target does not stop all the docker containers started by run-server. To stop the running docker containers:

    make stop-docker

15. Set your options:

    Some behaviors can be customized such as running the server in the foreground as described in the config.mk file in the server directory. See that file for details.

Build the Mattermost Server

The make package command will package the application and place it under the ./dist directory. You can distribute the .tar.gz file if you wish the run the application elsewhere. Note that you would need to run make build before this to build the binaries.

Develop Mattermost without Docker

1. Install make.

   • On Ubuntu, you can install build essential tools which will also take care of installing the make:

     sudo apt install build-essential

2. Copy the file server/config.mk as server/config.override.mk and set MM_NO_DOCKER to true in the copy.

3. Install PostgreSQL

4. Run psql postgres. Then create mmuser by running CREATE ROLE mmuser WITH LOGIN PASSWORD 'mostest_password';

5. Modify the role to give rights to create a database by running ALTER ROLE mmuser CREATEDB;

6. Confirm the role rights by running \du

7. Before creating the database, exit by running \q

8. Login again via mmuser by running psql postgres -U mmuser

9. Create the database by running CREATE DATABASE mattermost_test; and exit again with \q

10. Login again with psql postgres and run GRANT ALL PRIVILEGES ON DATABASE mattermost_test TO mmuser; to give all rights to mmuser

11. Install Go.

12. Increase the number of available file descriptors. Update your shell's initialization script (e.g. .bashrc or .zshrc), and add the following:

    ulimit -n 8096

13. If you don't have it already, install libpng with your preferred package manager.

    • If you are on ARM based Mac, you'll need to install Rosetta to make libpng work. Rosetta can be installed by the following command-

      softwareupdate --install-rosetta

14. Fork https://github.com/mattermost/mattermost.

15. Clone the Mattermost source code from your fork:

    git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost.git
    cd mattermost

16. Install NVM and use it to install the required version of Node.js:

    • First, install NVM by following these instructions.
    • Then, use NVM to install the correct version of Node.js for the Mattermost web app (this should be run within the webapp directory):

      cd webapp
      nvm install
      cd ..

    • NOTE: If you get zsh: command not found: nvm when running nvm install, you will need to add the following to your ~/.zshrc file:

      export NVM_DIR="$HOME/.nvm"
      [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
      [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

17. Start the server:

    cd server
    make run-server

18. Test your environment to ensure that the server is running by running the following in a different terminal session:

    curl -s http://localhost:8065/api/v4/system/ping | jq .

    If successful, the curl step will return a JSON object:

    {"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}

    Alternately, you can enter http://localhost:8065/api/v4/system/ping in a web browser.

19. Set up up your admin user using mmctl:

    bin/mmctl user create --local --email ADMIN_EMAIL --username ADMIN_USERNAME --password ADMIN_PASSWORD --system-admin

    • Note: ADMIN_PASSWORD must be 8 characters or more.

    • Optionally, you can also populate the database with random sample data as well:

      bin/mmctl --local sampledata

20. Start the web app (in another terminal window):

    cd PATH_TO_MATTERMOST_REPO/webapp
    make run

21. Open the web app by going to http://localhost:8065 in your browser or by adding it to the Mattermost desktop app.

22. Stop the server:

    cd PATH_TO_MATTERMOST_REPO/server
    make stop-server

23. Set your options: Some behaviors can be customized such as running the server in the foreground as described in the config.mk file in the server directory. See that file for details.