Installing Mattermost on Windows
Mattermost isn’t officially supported on Windows and isn’t able to be run natively on an IIS server, however, by following this guide, you’ll install and configure a Mattermost server to a production-ready state using the Windows Subsystem for Linux, as well as systemd-genie
to provide service capacities.
In this guide, we will:
- Install and configure the Windows Subsystem For Linux (WSL)
- Select and Install an operating system on WSL
- Install and configure
systemd-genie
to provide a virtualizedsystemd
connection, as well as the required dependencydotnet-core-5.0
- Install and configure the Mattermost Server with MySQL and Apache
Important: Compatibility
When installing, there are several compatibilities I urge you to keep in mind as you choose your WSL operating system. The systemd-genie
tool requires the dotnet-runtime-5.0
from Microsoft - this package is incompatible with several operating systems, and you need to be careful not to select an operating system that will prevent you from installing this critical dependency to the genie package. A complete list of dotnet-runtime-5.0
compatible operating systems can be viewed here. In addition, the systemd-genie
package itself is only been tested on a very small number of operating systems, due to its generally limited scope of use. The distributions provided below have been tested to ensure general functionality - all other distributions are at your own risk, and may not provide the expected results.
systemd-genie
has been tested with:
- Ubuntu & Debian Derivatives (Installable with
APT
, or from project releases) - Arch package (
.zst
, available from the project releases) - Fedora package (
.rpm
, available from the project releases)
Part One - Installing the Windows Subsystem for Linux
Step 1 - Enable the Windows Subsystem for Linux
Before you can install a Linux distribution onto WSL, you must first enable WSL, and make sure that it is the correct version.
First, __open __a PowerShell command prompt as an administrator, and run the following function to enable WSL:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Then, execute the following command in PowerShell to enable the virtualization platform on your Windows computer:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Step 2 - Check requirements for running WSL2
Windows documentation states:
To update to WSL 2, you must be running Windows 10.
For x64 systems: Version 1903 or higher, with Build 18362 or higher.
For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.
Builds lower than 18362 do not support WSL 2. Use the Windows Update Assistant to update your version of Windows.
To check your version and build number, selectWindows logo key + R
, typewinver
, select OK. Update to the latest Windows version in the Settings menu.
This means that your system may not be compatible with WSL2, which is required in order to complete the Mattermost installation.
Step 3 - Download the Linux Kernel Update Package
This package update provides your system’s virtualization environment with critical files and dependencies it needs to run WSL2.
Download and install the appropriate package for your system directly from the Windows documentation, or from the Microsoft direct download links provided below
-
Note: If you’re not sure what system type you have, open a command prompt or PowerShell and run the command
systeminfo | find "System Type"
Run the package you downloaded in the previous step, accept the prompts, and you are good to go!
Step 4 - Set WSL2 as your default version
Setting WSL2 as the default version ensures that it will be used in all future Linux distribution installations.
Run this command to set WSL2 as the default version:
wsl --set-default-version 2
Step 5 - Installing a Linux Distribution
To install a Linux distribution, such as Ubuntu 18.04 (Bionic Beaver), open the Microsoft store, and search for an operating system. There are numerous distributions available through the Microsoft Store, however, this tutorial will use Ubuntu 18.04 (Bionic Beaver).
Click here to open the Microsoft Store and install Ubuntu 18.04 (Bionic Beaver) on WSL2.
Note: The first time you run your WSL distribution, you’re prompted to create a username and password. Take care to remember this password - it is your root (sudo
) password - loss of this password will require resetting your distribution!
Part 2 - Install and Configure systemd-genie
Step 1 - Install dotnet-runtime
The dotnet-runtime
is an important part of the genie
, and is required in order for genie
to function correctly. As such, we need to install dotnet-runtime-5.0
in Ubuntu, prior to installing genie
.
First, to allow us to easily install updates, we’re going to add the Microsoft APT repository to our sources file:
wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
Note: The above command is only for Ubuntu 18.04 - if you are installing with a different OS, follow the instructions found here to add the Microsoft APT repository to your sources.
Now that we have added the APT repository to the system, let’s install the dotnet-runtime
:
sudo apt-get update; \
sudo apt-get install -y apt-transport-https && \
sudo apt-get update && \
sudo apt-get install -y aspnetcore-runtime-5.0
Once the installation process has completed, you have successfully installed the dotnet-runtime
, and are ready to proceed to the next step!
Step 2 - Add the systemd-genie
Repository and Install
Debian/Ubuntu Only - the following step of the installation process is for Debian/Ubuntu Linux distributions only. Please refer to the official systemd-genie
installation documentation here for all other distributions.
To install systemd-genie
, run the following command:
sudo apt-get install apt-transport-https -y
sudo wget -O /etc/apt/trusted.gpg.d/wsl-transdebian.gpg https://arkane-systems.github.io/wsl-transdebian/apt/wsl-transdebian.gpg
sudo chmod a+r /etc/apt/trusted.gpg.d/wsl-transdebian.gpg
source /etc/os-release
cat << EOF | sudo tee /etc/apt/sources.list.d/wsl-transdebian.list
deb https://arkane-systems.github.io/wsl-transdebian/apt/ $VERSION_CODENAME main
deb-src https://arkane-systems.github.io/wsl-transdebian/apt/ $VERSION_CODENAME main
EOF
sudo apt-get update
sudo apt-get install systemd-genie -y
Step 3 - Configure systemd-genie
to reduce startup wait time
Due to the fact that WSL is, by nature, not designed to run with systemd
or D-Bus, there are some compatibility issues with the initialization of the genie bottle, mainly related to systemd
timing-out on initialization. To reduce the wait time, we can reduce the number of seconds genie is configured to wait for systemd
to a much lower number than the default 180 seconds. To change the timeout, open the file /etc/genie.ini
in your favorite text editor, and change systemd-timeout
to your preferable wait time - in the example provided, it is 5 seconds.
[genie]
secure-path=/lib/systemd:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
unshare=/usr/bin/unshare
update-hostname=true
clone-path=false
clone-env=WSL_DISTRO_NAME,WSL_INTEROP,WSLENV,DISPLAY,WAYLAND_DISPLAY,PULSE_SERVER
systemd-timeout=5
Next, we need to add additional environment variables to the .bashrc
files of our root and non-root users.
Open ~/.bashrc
in a text editor:
nano ~/.bashrc
Copy and paste the following two lines into the bottom of the file:
sudo /etc/init.d/dbus start &> /dev/null
export XDG_RUNTIME_DIR=/run/user/$UID
Save the file, exit, and repeat, but prepend sudo
to form the command sudo nano ~/.bashrc
;
Finally, execute the command source ~/.bashrc
and you’re good to go!
Tip:
This is an excerpt from the official genie
documentation, addressing a possible issue you will encounter:
If genie (1.31+) seems to be blocked at the
“
Waiting for systemd...!!!!!
”stage, this is because of the new feature in 1.31 that waits for all
systemd
services/units to have started up before continuing, to ensure that they have started before you try and do anything that might require them. (I.E., it waits for the point at which a normal Linux system would have given you a login prompt.) It does this by waiting forsystemd
to reach the “running” state.If it appears to have blocked, wait until the timeout (by default, 60 seconds), at which point a list of units which have not started property will be displayed. Fixing or disabling those units such that
systemd
can start properly will also allow genie to start properly. Known-problematic units are listed on the genie wiki.
Note that some systemd
modules fail to start properly, but this doesn’t adversely affect your Mattermost installation, and you will still be able to deploy your server.
Part Three - Starting and Entering the systemd-genie
Bottle
Once genie and its dependencies are installed, and the system is using systemd
, launch genie
and enter the environment (referred to as a bottle
).
Launch Genie from your command prompt:
genie -l
This will provide you with a login screen - the credentials are the username and password you assigned during initial installation.
Now that you are logged in, you should see something similar to the image below - you are now inside the genie bottle, and can use systemctl
and systemd
.
Part 3 - Install Mattermost
Install Mattermost, MySQL, and Apache. If you prefer to use a database other than MySQL, please refer to the manual installation instructions.
Step One - Install MySQL
Run the following command to install MySQL and setup your Mattermost database and user with an interactive prompt:
bash -c "$(curl -s https://gist.githubusercontent.com/XxLilBoPeepsxX/cb87e6e1f91909cf9f6e7ddba0334fc7/raw/1d4c81b10d469b5e9c3adf3b1412395d437172c3/initdb.sh)"
Important: Take care to remember the name of the database, user, and password that you configure during setup - you will need this to complete the configuration of Mattermost
Part Two - Download and Prepare Mattermost
- Download the latest version of the Mattermost Server. In the following command, replace
X.X.X
with the version that you want to download:
wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz
- Extract the Mattermost Server files:
tar -xvzf mattermost*.gz
- Move the extracted file to the
/opt
directory:
sudo mv mattermost /opt
- Create the storage directory for files:
sudo mkdir /opt/mattermost/data
Note: The storage directory contains all Mattermost files and image posts, so make sure that the drive is big enough.
- Set up a system user and group called
mattermost
that will run this service, and set the ownership and permissions:
sudo useradd --system --user-group mattermost
- Set the user and group mattermost as the owner of the Mattermost files:
sudo chown -R mattermost:mattermost /opt/mattermost
- Give write permissions to the mattermost group:
sudo chmod -R g+w /opt/mattermost
Part Three - Configuring Mattermost
First, we must set up the database driver in the file /opt/mattermost/config/config.json
. Open the file in a text editor and make the following changes:
- Set
"DriverName"
to"mysql"
- Set
"DataSource"
to the following value, replacing<mmuser-password>
and<host-name-or-IP>
with the appropriate values. Also make sure that the database name ismattermost
(or the name of the database you created) instead ofmattermost_test
:
"mmuser:<mmuser-password>@tcp(<host-name-or-IP>:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s"
-
Also set
"SiteURL"
to the full base URL of the site (e.g."https://mattermost.example.com"
). -
Test the Mattermost server to make sure everything works.
a. Change to the
mattermost
directory:cd /opt/mattermost
b. Start the Mattermost server as the user mattermost:
sudo -u mattermost ./bin/mattermost
When the server starts, it shows some log information and the text Server is listening on :8065
. You can stop the server by pressing CTRL+C
in the terminal window.
Part Four - Configuring Mattermost to run with systemd
as a service
- Create a
systemd
unit file:
sudo touch /lib/systemd/system/mattermost.service
- Open the unit file as root in a text editor, and copy the following lines into the file:
[Unit]
Description=Mattermost
After=network.target
After=mysql.service
BindsTo=mysql.service
[Service]
Type=notify
ExecStart=/opt/mattermost/bin/mattermost
TimeoutStartSec=3600
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost
LimitNOFILE=49152
[Install]
WantedBy=mysql.service
- Make
systemd
load the new unit.
sudo systemctl daemon-reload
- Check to make sure that the unit was loaded.
sudo systemctl status mattermost.service
You should see an output similar to the following:
● mattermost.service - Mattermost
Loaded: loaded (/lib/systemd/system/mattermost.service; disabled; vendor preset: enabled)
Active: inactive (dead)
- Start the service.
sudo systemctl start mattermost.service
- Verify that Mattermost is running.
curl http://localhost:8065
You should see the HTML that’s returned by the Mattermost server.
- Set Mattermost to start on machine start up.
sudo systemctl enable mattermost.service
Now that the Mattermost server is up and running, you can do some initial configuration and setup.
Part Four - Configuring Apache2 as a proxy for Mattermost Server
In order to use Apache as our reverse proxy, we must make sure we have the correct modules installed and enabled, as well as ensure that proper security steps are taken.
-
Make sure the Apache modules
mod_rewrite
,mod_proxy
,mod_proxy_http
, andmod_proxy_wstunnel
are installed and enabled. If not, follow the instructions from your Linux distribution to do so. -
Create the configuration file for the Mattermost server’s
virtualhost
. It is often helpful to start with a copy of000-default.conf
ordefault-ssl.conf
. -
Edit your configuration using the guide below:
- If you’re not setting up a subdomain, your
ServerName
will simply be set to your main domain name (mydomain.com
). -
ServerAlias
can been added too if you want to capturewww.mydomain.com
. - Remember to change the values to match your server’s name, etc.
- If you have enabled TLS in the Mattermost settings, you must use the protocol
wss://
instead ofws://
in theRewriteRule
. - To serve requests on a different port (such as 8443), in addition to setting the port in the
VirtualHost
element, addListen 8443
on a separate line before theVirtualHost
line.
- If you’re not setting up a subdomain, your
<VirtualHost *:80>
# If you're not using a subdomain you may need to set a ServerAlias to:
# ServerAlias www.mydomain.com
ServerName mysubdomain.mydomain.com
ServerAdmin hostmaster@mydomain.com
ProxyPreserveHost On
# Set web sockets
RewriteEngine On
RewriteCond %{REQUEST_URI} /api/v[0-9]+/(users/)?websocket [NC,OR]
RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC,OR]
RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
RewriteRule .* ws://127.0.0.1:8065%{REQUEST_URI} [P,QSA,L]
<Location />
Require all granted
ProxyPass http://127.0.0.1:8065/
ProxyPassReverse http://127.0.0.1:8065/
ProxyPassReverseCookieDomain 127.0.0.1 mysubdomain.mydomain.com
</Location>
</VirtualHost>
Because you’ll likely have not set up the subdomain before now on Apache2, run a2ensite mysubdomain.mydomain.com
to enable the site (do not run a2ensite mysubdomain.mydomain.com.conf
).
-
Restart Apache2.
- On Ubuntu 14.04:
sudo service apache2 restart
- On Ubuntu 16.04+:
sudo systemctl restart apache2
- On Ubuntu 14.04:
You should be all set! Ensure that your Mattermost config file is pointing to the correct URL (which may include a port), and then ensure that your socket connection is not dropping once deployed. To prevent external access to Mattermost on port 8065, in the config file, set ListenAddress
to localhost:8065
instead of :8065
.
Part Five - Configuring HTTPS with LetsEncrypt
In order to use Apache as a reverse proxy for the Mattermost Server, you need to install and enable the following apache modules: mod_rewrite
, mod_proxy
, mod_proxy_http
, mod_headers
, and mod_proxy_wstunnel
. Follow the installation instructions for your Linux distribution.
Once you’ve configured Apache2 as a proxy for your Mattermost Server, the easiest way to enable SSL on Apache2 is via Let’s Encrypt and Certbot.
Certbot allows you to easily generate and install the SSL certificate for your domain name, with an easy to use, interactive prompt.
Install Certbot with the following command:
sudo apt-get install python3-certbot* -y
When you have completed the installation, run the command certbot
, and you will see the following menu:
Select the Apache Web Server, and continue by responding to the prompts of the installer. When you complete the verification, select the option to automatically install the HTTPS certificate, and you will not need to do any further configuration.
In the future, there are plans to develop a custom script that will assist you in the deployment of SSL certificates, stay tuned for updates in the near future!