snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/develop/contribute/developer-setup/docker.md

@@ -0,0 +1,133 @@
+---
+title: "Docker Services"
+sidebar_position: 1
+---
+
+By default, only a small number of required Docker services are started to support basic development:
+
+```
+ENABLED_DOCKER_SERVICES="postgres mysql inbucket"
+```
+
+But there are many additional services ready to work with your local environment. Note that some services will require a Mattermost Enterprise license.
+
+```
+ENABLED_DOCKER_SERVICES="postgres mysql inbucket minio openldap dejavu keycloak elasticsearch grafana prometheus promtail loki"
+```
+
+To customize which services are started, either export the above environment variable or copy [`config.mk`](https://github.com/mattermost/mattermost/blob/master/server/config.mk) as `config.override.mk` to tune appropriately.
+
+## postgres
+
+From https://www.postgresql.org/:
+
+> The official site for PostgreSQL, the world's most advanced open source database.
+
+This is the default and recommended database to use with Mattermost. No additional configuration should be required, but the following settings apply to a Mattermost instance using Postgres:
+
+```
+MM_SQLSETTINGS_DRIVERNAME=postgres
+MM_SQLSETTINGS_DATASOURCE=postgres://mmuser:mostest_password@localhost:5432/mattermost_test?sslmode=disable\u0026connect_timeout=10
+```
+
+## mysql
+
+From https://dev.mysql.com/doc/refman/8.3/en/introduction.html:
+
+> The MySQL software delivers a very fast, multithreaded, multi-user, and robust SQL (Structured Query Language) database server.
+
+This is an alternate database supported by Mattermost, but not recommended for new deployments.
+
+To use with Mattermost, be sure to configure the following settings:
+```
+MM_SQLSETTINGS_DRIVERNAME=mysql
+MM_SQLSETTINGS_DATASOURCE=mmuser:mostest_password@tcp(localhost:3306)/mattermost_test?charset=utf8mb4,utf8\u0026readTimeout=30s\u0026writeTimeout=30s
+```
+
+## inbucket
+
+From https://inbucket.org/about/:
+
+> Inbucket is an email testing application; it will accept messages for any email address and make them available to view via a web interface. If you've ever used mailinator.com, you already have a good idea of what Inbucket does. The benefit of Inbucket is that it is an application instead of a hosted service; you may run it on your own private network, or even your desktop. 
+
+Use this during development to "receive" email confirmations, password resets, or message notifications.
+
+To use with Mattermost, be sure to configure the following settings:
+```
+MM_EMAILSETTINGS_ENABLESMTPAUTH=false
+MM_EMAILSETTINGS_SMTPUSERNAME=
+MM_EMAILSETTINGS_SMTPPASSWORD=
+MM_EMAILSETTINGS_SMTPSERVER=localhost
+MM_EMAILSETTINGS_SMTPPORT=10025
+```
+
+When running, access the web interface at [http://localhost:9001/](http://localhost:9001/).
+![inbucket](/img/docker/inbucket.png)
+
+## grafana
+
+From https://grafana.com/docs/
+
+> Collect, correlate, and visualize data with beautiful dashboards using our open source data visualization and monitoring solution.
+
+Grafana is where all the metrics and logs collected by Prometheus, Loki and promtail come together. Panels visualize the data and are grouped into dashboards. The home dashboard links out to various performance dashboards, lists which Docker services are currently online, has quick links to various filtered log views, and panels showing the most recent Mattermost and Docker container logs.
+
+When running, access the web interface at [http://localhost:3000](http://localhost:3000).
+![grafana](/img/docker/grafana.png)
+
+## prometheus
+
+From https://prometheus.io/docs/introduction/overview/:
+
+> Prometheus collects and stores its metrics as time series data, i.e. metrics information is stored with the timestamp at which it was recorded, alongside optional key-value pairs called labels.
+
+Mattermost exposes metrics at [http://localhost:8067/metrics](http://localhost:8067/metrics) which are scraped periodically by Prometheus to form a time series database. While you can access Prometheus directly to view and graph this collected data, typically this is used in tandem with Grafana for a rich dashboard experience.
+
+To use with Mattermost, be sure to install a Mattermost enterprise license and configure the following settings:
+
+```
+MM_METRICSSETTINGS_ENABLE=true
+```
+
+When running, access the web interface at [http://localhost:9090/](http://localhost:9090).
+![prometheus](/img/docker/prometheus.png)
+
+## promtail
+
+From https://grafana.com/docs/loki/latest/send-data/promtail/:
+
+> Promtail is an agent which ships the contents of local logs to a private Grafana Loki instance or Grafana Cloud. It is usually deployed to every machine that runs applications which need to be monitored.
+
+To use with Mattermost, be sure to enable file logs, with the containing directory automatically mounted as a volume for promtail to scrape and relay to Loki. Promtail is automatically configured to scrape all Docker container logs for use with Loki and Grafana.
+
+```
+MM_LOGSETTINGS_ENABLEFILE=true
+MM_LOGSETTINGS_FILELEVEL=debug
+MM_LOGSETTINGS_FILEJSON=true
+MM_LOGSETTINGS_FILELOCATION=logs
+```
+
+## loki
+
+From https://grafana.com/oss/loki/:
+
+> Loki is a log aggregation system designed to store and query logs from all your applications and infrastructure.
+
+Just as Prometheus is for metrics, think of Loki being for logs. Combined with promtail scraping the logs from Mattermost and all these supporting Docker containers, and Grafana for the frontend, Loki effectively provides a powerful user interface for slicing and dicing your developer logs.
+
+## keycloak
+
+From https://www.keycloak.org/documentation:
+
+> Keycloak is an open source identity and access management solution.
+
+Keycloak can be used as a SAML identity provider with your local setup. See the setup instructions [here](https://github.com/mattermost/mattermost/blob/master/server/build/docker/keycloak/README.md).
+
+# Other Docker services
+
+Other Docker services supported by the development environment include:
+* minio
+* openldap
+* dejavu
+* elasticsearch
+

docs/develop/contribute/developer-setup/index.md

@@ -0,0 +1,234 @@
+---
+title: "Developer setup"
+sidebar_position: 1
+---
+
+Set up your development environment for building, running, and testing Mattermost.
+
+
+<Note title="Note">
+- If you're migrating from before the monorepo see the [migration notes](/developers/contribute/monorepo-migration-notes).
+- If you're developing plugins, see the plugin [developer setup](/developers/integrate/plugins/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](https://mattermost.com/trademark-standards-of-use/).
+</Note>
+
+
+# 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](https://learn.microsoft.com/en-us/windows/wsl/install) by running the following command as an administrator in PowerShell: `wsl --install`
+2. [Install Docker Desktop for Windows](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers#install-docker-desktop) on your Windows machine. Alternatively, you can also [install](https://docs.docker.com/engine/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
+
+
+<Note title="Note">
+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.
+</Note>
+
+
+1. Install `make`.
+    - On Ubuntu, you can install `build essential` tools which will also take care of installing the `make`:
+
+        ```sh
+        sudo apt install build-essential
+        ```
+
+1. Install and run [Docker](https://www.docker.com/). If you don't want to use Docker, you can follow [this guide](#develop-mattermost-without-docker).
+    - 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
+
+1. Install [Go](https://go.dev/).
+    - Version 1.21 or higher is required.
+
+1. Increase the number of available file descriptors. Update your shell's initialization script (e.g. `.bashrc` or `.zshrc`), and add the following:
+
+    ```sh
+    ulimit -n 8096
+    ```
+
+1. 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](https://support.apple.com/en-in/HT211861) to make `libpng` work. Rosetta can be installed by the following command-
+
+        ```sh
+        softwareupdate --install-rosetta
+        ```
+
+1. Fork https://github.com/mattermost/mattermost.
+
+1. Clone the Mattermost source code from your fork:
+
+    ```sh
+    git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost.git
+    ```
+
+1. Install NVM and use it to install the required version of Node.js:
+
+    1. Install [NVM](https://github.com/nvm-sh/nvm) by following [these instructions](https://github.com/nvm-sh/nvm#installing-and-updating).
+
+    1. Then, use NVM to install the correct version of Node.js for the Mattermost web app (this should be run within the `webapp` directory):
+        ```sh
+        nvm install
+        ```
+
+1. Start the server:
+
+    ```sh
+    cd server
+    make run-server
+    ```
+
+1. Test your environment to ensure that the server is running:
+
+    ```sh
+    curl http://localhost:8065/api/v4/system/ping
+    ```
+
+    If successful, the `curl` step will return a JSON object:
+    ```json
+    {"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}
+    ```
+
+1. Set up up your admin user using mmctl:
+
+   ```sh
+   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:
+
+       ```sh
+       bin/mmctl sampledata
+       ```
+
+1. Start the web app:
+
+    ```sh
+    cd webapp
+    make run
+    ```
+
+1. Open the web app by going to http://localhost:8065 in your browser or by adding it to the Mattermost desktop app.
+
+1. Stop the server:
+
+    ```sh
+    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:
+
+    ```sh
+    make stop-docker
+    ```
+
+1. 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`:
+        ```sh
+        sudo apt install build-essential
+        ```
+1. Copy the file `server/config.mk` as `server/config.override.mk` and set `MM_NO_DOCKER` to `true` in the copy.
+1. Install [PostgreSQL](https://www.postgresql.org/download/)
+1. Run `psql postgres`. Then create `mmuser` by running `CREATE ROLE mmuser WITH LOGIN PASSWORD 'mostest_password';`
+1. Modify the role to give rights to create a database by running `ALTER ROLE mmuser CREATEDB;`
+1. Confirm the role rights by running `\du`
+1. Before creating the database, exit by running `\q`
+1. Login again via `mmuser` by running `psql postgres -U mmuser`
+1. Create the database by running `CREATE DATABASE mattermost_test;` and exit again with `\q`
+1. Login again with `psql postgres` and run `GRANT ALL PRIVILEGES ON DATABASE mattermost_test TO mmuser;` to give all rights to `mmuser`
+1. Install [Go](https://go.dev/).
+1. Increase the number of available file descriptors. Update your shell's initialization script (e.g. `.bashrc` or `.zshrc`), and add the following:
+    ```sh
+    ulimit -n 8096
+    ```
+
+1. 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](https://support.apple.com/en-in/HT211861) to make `libpng` work. Rosetta can be installed by the following command-
+        ```sh
+        softwareupdate --install-rosetta
+        ```
+
+1. Fork https://github.com/mattermost/mattermost.
+1. Clone the Mattermost source code from your fork:
+    ```sh
+    git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost.git
+    cd mattermost
+    ```
+
+1. Install NVM and use it to install the required version of Node.js:
+    - First, install [NVM](https://github.com/nvm-sh/nvm) by following [these instructions](https://github.com/nvm-sh/nvm#installing-and-updating).
+    - Then, use NVM to install the correct version of Node.js for the Mattermost web app (this should be run within the `webapp` directory):
+        ```sh
+        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:
+        ```zsh
+        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
+        ```
+
+1. Start the server:
+    ```sh
+    cd server
+    make run-server
+    ```
+
+1. Test your environment to ensure that the server is running by running the following in a different terminal session:
+
+    ```sh
+    curl -s http://localhost:8065/api/v4/system/ping | jq .
+    ```
+
+    If successful, the `curl` step will return a JSON object:
+    ```json
+    {"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}
+    ```
+
+    Alternately, you can enter `http://localhost:8065/api/v4/system/ping` in a web browser.
+
+1. Set up up your admin user using mmctl:
+
+   ```sh
+   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:
+
+       ```sh
+       bin/mmctl --local sampledata
+       ```
+
+1. Start the web app (in another terminal window):
+
+    ```sh
+    cd PATH_TO_MATTERMOST_REPO/webapp
+    make run
+    ```
+
+1. Open the web app by going to http://localhost:8065 in your browser or by adding it to the Mattermost desktop app.
+
+1. Stop the server:
+    ```sh
+    cd PATH_TO_MATTERMOST_REPO/server
+    make stop-server
+    ```
+
+1. 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.