Edit on GitHub

Set up your development environment

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

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 

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

    • 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):

      nvm install
      
  9. Start the server:

    cd server
    make run-server
    
  10. Test your environment:

    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. Run the webapp and watch:

    make run
    
  12. 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
    
  13. 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.

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. Set MM_NO_DOCKER to true in the server/config.mk file.

  3. Install PostgreSQL

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

  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
    
  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):
      nvm install
      
  17. Start the server:

    cd server
    make run-server
    
  18. Test your environment:

    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"}
    
  19. Run the webapp and watch:

    make run
    
  20. Stop the server:

    make stop-server
    
  21. 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.

Did you find what you were looking for?

Thank you! We appreciate your feedback.
×

Tell us more

Your feedback helps us improve the Mattermost developer documentation.

Have a feature request? Share it here.

Having issues? Join our Community server.