We're Hiring!

Mattermost Discussion Forums

[Guide] Installing Mattermost on Windows

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 virtualized systemd connection, as well as the required dependency dotnet-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:


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, select Windows logo key + R, type winver, 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

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 for systemd 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

image-20210630210246356

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.

image-20210630212006836


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

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:

  1. Set "DriverName" to "mysql"
  2. 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 is mattermost(or the name of the database you created) instead of mattermost_test:
"mmuser:<mmuser-password>@tcp(<host-name-or-IP>:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s"
  1. Also set "SiteURL" to the full base URL of the site (e.g. "https://mattermost.example.com").

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

  1. Create a systemd unit file:
sudo touch /lib/systemd/system/mattermost.service
  1. 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
  1. Make systemd load the new unit.
sudo systemctl daemon-reload
  1. 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)
  1. Start the service.
sudo systemctl start mattermost.service
  1. Verify that Mattermost is running.
curl http://localhost:8065

You should see the HTML that’s returned by the Mattermost server.

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

  1. Make sure the Apache modules mod_rewrite , mod_proxy, mod_proxy_http, and mod_proxy_wstunnel are installed and enabled. If not, follow the instructions from your Linux distribution to do so.

  2. Create the configuration file for the Mattermost server’s virtualhost. It is often helpful to start with a copy of 000-default.conf or default-ssl.conf.

  3. Edit your configuration using the guide below:

    1. If you’re not setting up a subdomain, your ServerName will simply be set to your main domain name (mydomain.com).
    2. ServerAlias can been added too if you want to capture www.mydomain.com.
    3. Remember to change the values to match your server’s name, etc.
    4. If you have enabled TLS in the Mattermost settings, you must use the protocol wss:// instead of ws:// in the RewriteRule.
    5. To serve requests on a different port (such as 8443), in addition to setting the port in the VirtualHost element, add Listen 8443 on a separate line before the VirtualHost line.
<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

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:

image-20210702122811911

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!


Written by Andrew Henke - Please feel free to contact me for questions, troubleshooting, or assistance.
2 Likes

@XxLilBoPeepsxX Thank you for this excellent guide! Well written :+1:

1 Like

Thank you so much, I appreciate it!