Set up your development environment for building, running, and testing the Mattermost server.
Note: If you’re developing plugins, see the plugin developer setup documentation.
For minimum software requirements, see the following table:
Software | Minimum Version |
---|---|
Docker | 17.12.0+ |
Docker Compose | 1.21.0+ |
Go | 1.18.0+ |
Install and configure Docker CE: https://docs.docker.com/docker-for-mac/.
Note: MM-9791 introduced using docker-compose to manage containers. To preserve your data on upgrade, execute the following steps.
First, backup from any existing containers:
mysqldump -h 127.0.0.1 --column-statistics=0 -u mmuser -p mattermost_test > mm_mysql_backup.sql
pg_dump -U mmuser -W -d mattermost_test -h 127.0.0.1 > mm_postgres_backup.bak
Then after upgrading and starting the new docker-compose managed containers, restore the data:
mysql -u mmuser -p -h 127.0.0.1 mattermost_test < mm_mysql_backup.sql
psql -U mmuser -W -h 127.0.0.1 -f mm_postgres_backup.bak mattermost_test
If you don’t migrate your data, the new, docker-compose-managed containers will start out empty. To remove the old containers – destroying any existing data – use make clean-old-docker
.
Download and install homebrew: https://brew.sh/.
Install Go:
brew install go
Update your shell’s initialization script (e.g. .bashrc
or .zshrc
) and add the following:
ulimit -n 8096
Clone the Mattermost source code from your fork:
git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost-server.git
Start the server:
cd mattermost-server
make run-server
Note: If you see lot of nc: bad address 'elasticsearch'
messages, eventually exiting with the message Service elasticsearch:9200 did not start within 300 seconds. Aborting...
, increase the memory available for the Docker Engine by going to Docker’s preferences -> Advanced.
Note: If you see an error which says Failed to ping DB
, it’s probably due to a conflict between the PostgreSQL service in Docker and the one which is running system-wide. You can stop the system-wide server temporarily by running brew services stop postgres
in your terminal, then restart the Docker service.
Test your environment:
curl http://localhost:8065/api/v4/system/ping
make stop-server
If successful, the curl
step will return a JSON object:
{"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}
Note: Browsing directly to http://localhost:8065/ will display a 404 Not Found
until the web app is configured. See [Web App Developer Setup]({{< ref “/contribute/webapp/developer-setup” >}}) and [Mobile App Developer Setup]({{< ref “/contribute/mobile/developer-setup” >}}) for additional setup.
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
Install and configure Docker CE:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $(whoami)
docker login
If you prefer to perform these steps manually:
Note: MM-9791 introduced using docker-compose to manage containers. To preserve your data on upgrade, execute the following steps.
First, backup from any existing containers:
mysqldump -h 127.0.0.1 --column-statistics=0 -u mmuser -p mattermost_test > mm_mysql_backup.sql
pg_dump -U mmuser -W -d mattermost_test -h 127.0.0.1 > mm_postgres_backup.bak
Then after upgrading and starting the new docker-compose managed containers, restore the data:
mysql -u mmuser -p -h 127.0.0.1 mattermost_test < mm_mysql_backup.sql
psql -U mmuser -W -h 127.0.0.1 -f mm_postgres_backup.bak mattermost_test
If you don’t migrate your data, the new, docker-compose-managed containers will start out empty. To remove the old containers and destroy any existing data use make clean-old-docker
.
Install docker-compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Install Go (modify installation to latest Go version from https://golang.org/dl/):
sudo apt-get install -y build-essential
sudo rm -rf /usr/local/go
wget https://dl.google.com/go/go$VERSION.$OS-$ARCH.tar.gz
sudo tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz
Update your shell’s initialization script (e.g. .bashrc
or .zshrc
) and add the following:
export PATH=$PATH:/usr/local/go/bin
Edit /etc/security/limits.conf
as an administrator (e.g. sudo) and add the following lines, replacing {username}
with your username:
{username} soft nofile 8096
{username} hard nofile 8096
Log out and log back in to effect the changes above.
Clone the Mattermost source code from your fork:
git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost-server.git
Start the server and test your environment:
cd mattermost-server
make run-server
curl http://localhost:8065/api/v4/system/ping
make stop-server
If successful, the curl
step will return a JSON object:
{"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}
Note: Browsing directly to http://localhost:8065/ will display 404 Not Found
until the web app is configured. See [Web App Developer Setup]({{< ref “/contribute/webapp/developer-setup” >}}) and [Mobile App Developer Setup]({{< ref “/contribute/mobile/developer-setup” >}}) for additional setup.
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
This is an unofficial guide. Community testing, feedback, and improvements are welcome and greatly appreciated.
Install the Windows Subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/install-win10.
Note: Docker for Windows expects path to have the format /c/foo/bar
, but WSL uses /mnt/c/foo/bar
instead.
Run winver
and check which version of Windows you have. If you are using 1803
or higher, then you need to create a file /etc/wsl.conf
with the following content to make sure your drives are mounted at the root rather than inside /mnt
:
[automount]
root = /
If you are using an older version than 1803
, you need to create custom bind points:
sudo mkdir /c
sudo mount --bind /mnt/c /c
For more on how to properly set up Docker for Windows and WSL see here.
Install and set up Docker:
mattermost-server
from.Note: MM-9791 introduced using docker-compose to manage containers. To preserve your data on upgrade, execute the following steps.
First, backup from any existing containers:
mysqldump -h 127.0.0.1 --column-statistics=0 -u mmuser -p mattermost_test > mm_mysql_backup.sql
pg_dump -U mmuser -W -d mattermost_test -h 127.0.0.1 > mm_postgres_backup.bak
Then after upgrading and starting the new docker-compose managed containers, restore the data:
mysql -u mmuser -p -h 127.0.0.1 mattermost_test < mm_mysql_backup.sql
psql -U mmuser -W -h 127.0.0.1 -f mm_postgres_backup.bak mattermost_test
If you don’t migrate your data, the new, docker-compose-managed containers will start out empty. To remove the old containers and destroy any existing data use make clean-old-docker
.
Install docker-compose (using bash)
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Install Go using bash (modify installation to latest Go version from https://golang.org/dl/):
sudo apt-get install -y build-essential
sudo rm -rf /usr/local/go
wget https://dl.google.com/go/go$VERSION.$OS-$ARCH.tar.gz
sudo tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz
Set up your Go workspace:
mkdir d:\Projects\go
ln -s "/mnt/d/Projects/go" /home/<Linux User>/go
Update your shell’s initialization script (e.g. .bashrc
or .zshrc
) and add the following:
export PATH=$PATH:/usr/local/go/bin
ulimit -n 8096
Reload your bash configuration to effect the changes above:
source ~/.bashrc
Fork Mattermost server on GitHub from https://github.com/mattermost/mattermost-server.
Clone the Mattermost source code from your fork:
git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost-server.git
Start the server and test your environment:
cd mattermost-server
make run-server
curl http://localhost:8065/api/v4/system/ping
make stop-server
If successful, the curl
step will return a JSON object containing "status":"OK"
.
Note: Browsing directly to http://localhost:8065/ will display 404 Not Found
until the web app is configured. See [Web App Developer Setup]({{< ref “/contribute/webapp/developer-setup” >}}) and [Mobile App Developer Setup]({{< ref “/contribute/mobile/developer-setup” >}}) for additional setup.
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
If you see an error like the input device is not a TTY. If you are using mintty, try prefixing the command with 'winpty'
, then reinstall Git for Windows and make sure you choose Use Windows' default console window instead of Use MinTTY.
The LDAP Docker container is sometimes slow to start. If you see the following message, either increase the wait time in the make file or run make run
twice in a row.
Ldap test user test.one
starting mattermost-openldap
ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
Makefile:102: recipe for target 'start-docker' failed
If you see an error like nc: bad address 'postgres'
when running make run-server
and PostgreSQL’s container just keeps restarting, check its logs in Docker Desktop. You should see something like:
LOG: input in flex scanner failed at file "/etc/postgresql/postgresql.conf" line 1
FATAL: configuration file "/etc/postgresql/postgresql.conf" contains errors
If that’s the case, postgresql.conf
is probably a directory rather than a file, which means the volume wasn’t mounted properly, so you are most likely missing some of the configuration changes from step 1 (Linux Subsystem Installation).
If you see an error like ERROR: for mattermost-postgres. Cannot create container for service postgres: status code not OK but 500: {"Message":"Unhandled exception: Drive has not been shared"}
, make sure you enabled file sharing for the drive that contains the mattermost-server
project.
Install and configure Docker CE:
sudo pacman -S docker
sudo gpasswd -a $USER docker
sudo systemctl enable docker.service
sudo systemctl start docker.service
newgrp docker
Note: MM-9791 introduced using docker-compose to manage containers. To preserve your data on upgrade, execute the following steps.
First, backup from any existing containers:
mysqldump -h 127.0.0.1 --column-statistics=0 -u mmuser -p mattermost_test > mm_mysql_backup.sql
pg_dump -U mmuser -W -d mattermost_test -h 127.0.0.1 > mm_postgres_backup.bak
Then after upgrading and starting the new docker-compose managed containers, restore the data:
mysql -u mmuser -p -h 127.0.0.1 mattermost_test < mm_mysql_backup.sql
psql -U mmuser -W -h 127.0.0.1 -f mm_postgres_backup.bak mattermost_test
If you don’t migrate your data, the new, docker-compose-managed containers will start out empty. To remove the old containers – destroying any existing data – use make clean-old-docker
.
Install docker-compose
sudo pacman -S docker-compose
Install Go:
sudo pacman -S base-devel
sudo pacman -S go
Update your shell’s initialization script (e.g. .bashrc
or .zshrc
) and add the following:
export PATH=$PATH:/usr/local/go/bin
Edit /etc/security/limits.conf
as an administrator (e.g. sudo
) and add the following lines, replacing {username}
with your username:
{username} soft nofile 8096
{username} hard nofile 8096
Logout and login to effect the changes above.
Clone the Mattermost source code from your fork:
git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost-server.git
Start the server and test your environment:
cd mattermost-server
make run-server
curl http://localhost:8065/api/v4/system/ping
make stop-server
If successful, the curl
step will return a JSON object:
{"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}
Note: Browsing directly to http://localhost:8065/ will display a 404 Not Found
until the web app is configured. See [Web App Developer Setup]({{< ref “/contribute/webapp/developer-setup” >}}) and [Mobile App Developer Setup]({{< ref “/contribute/mobile/developer-setup” >}}) for additional setup.
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
Install and configure Docker CE:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $(whoami)
docker login
If you prefer to perform these steps manually:
Note: MM-9791 introduced using docker-compose to manage containers. To preserve your data on upgrade, execute the following steps.
First, backup from any existing containers:
mysqldump -h 127.0.0.1 --column-statistics=0 -u mmuser -p mattermost_test > mm_mysql_backup.sql
pg_dump -U mmuser -W -d mattermost_test -h 127.0.0.1 > mm_postgres_backup.bak
Then after upgrading and starting the new docker-compose managed containers, restore the data:
mysql -u mmuser -p -h 127.0.0.1 mattermost_test < mm_mysql_backup.sql
psql -U mmuser -W -h 127.0.0.1 -f mm_postgres_backup.bak mattermost_test
If you don’t migrate your data, the new, docker-compose-managed containers will start out empty. To remove the old containers and destroy any existing data use make clean-old-docker
.
Install docker-compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Install Go (modify installation to latest Go version from https://golang.org/dl/):
sudo yum group install "Development Tools"
sudo yum install -y wget libpng12
sudo rm -rf /usr/local/go
wget https://dl.google.com/go/go$VERSION.$OS-$ARCH.tar.gz
sudo tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz
Update your shell’s initialization script (e.g. .bashrc
or .zshrc
) and add the following:
export PATH=$PATH:/usr/local/go/bin
Edit /etc/security/limits.conf
as an administrator (e.g. sudo) and add the following lines, replacing {username}
with your username:
{username} soft nofile 8096
{username} hard nofile 8096
Log out and log back in to effect the changes above.
Clone the Mattermost source code from your fork:
git clone https://github.com/YOUR_GITHUB_USERNAME/mattermost-server.git
Start the server and test your environment:
cd mattermost-server
make run-server
curl http://localhost:8065/api/v4/system/ping
make stop-server
If successful, the curl
step will return a JSON object:
{"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}
Note: Browsing directly to http://localhost:8065/ will display 404 Not Found
until the web app is configured. See [Web App Developer Setup]({{< ref “/contribute/webapp/developer-setup” >}}) and [Mobile App Developer Setup]({{< ref “/contribute/mobile/developer-setup” >}}) for additional setup.
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