Production Install on Windows Server (Unofficial)

Install Mattermost in production mode on one, two or three machines.

Attention

This unofficial guide is maintained by the Mattermost community and this deployment configuration is not yet officially supported by Mattermost, Inc. Community testing, feedback and improvements are welcome and greatly appreciated.

Install Windows Server 2012+

  1. Set up 3 machines with any edition of Windows Server 2012+ (except core) with 2GB of RAM or more. The servers will be used for the Web Proxy and SSL Termination, Mattermost, and Database. The screenshots used in this guide are from Microsoft Server 2012, but similar steps should work for other versions.
    • Optional: You can also use a single machine for all 3 components in this install guide, depending on the standards of your data center. In this case, replace all 10.0.0.* IP addresses with a single/common address.
  2. Make sure the systems are up to date with the most recent security patches by executing Windows Update.

Set up Database Server

  1. Login to the database server. For the purposes of this guide we will assume this server has an IP address of 10.0.0.1.

Install and Configure MySQL

  1. Download the MySQL 5.6+ installer, or (PostgreSQL 9.3+). For the purposes of this guide, we’ll be downloading and installing the latest version of MySQL Community Server Edition MSI-installer (version 5.7 at the time of writing this guide). Note that the appropriate link refers to 32-bit (as shown in the figure below); however, this installer is 32-bit but is capable of installing the 64-bit version of MySQL.
  2. Launch the installer.
  3. On the License Agreement page, Check the box to accept the license terms and press Next.
  4. On the Choosing a Setup Type choose Custom so you can decide exactly which packages to install. This is the only place where you can specify whether to install 32-bit or 64-bit MySQL Server.
  5. On the Select Products and Features page, select the 64bit version of MySQL Server.
  6. On the Check Requirements page, install any missing requirements by pressing the Execute button, or go back to the previous page and change the packages that will be installed to remove the requirement. Once all of the requirements are met, press the Next button.
  7. On the Installation page, you will be shown a list of software that will be installed. Press the Execute button to begin the installation. Once the installations have completed, press the Next button.
  8. On the Product Configuration page, press the Next button to begin the MySQL Server Configuration Wizard.
    1. On the Type and Networking page, select the appropriate Config Type based on your desired usage.
    2. On the Accounts and Roles page, enter a MySQL Root password and press the Next button.
    3. On the Windows Service page, keep the defaults and press the Next button.
    4. On the Plugins and Extensions page, keep the defaults and press the Next button.
    5. On the Apply Server Configuration page, press the Execute button to configure the MySQL Server installation.
  9. Returning to the Product Configuration page, press the Next button.
  10. On the Installation Complete page, press the Finish button.

Configure Windows PATH

Adding MySQL to the Windows PATH variable will allow you run various commands from the console, and allow 3rd party applications to execute various MySQL commands.

  1. Press the WIN + PAUSEBREAK key combination to open the System Control Panel Applet.
  2. Select the Advanced System Settings link.
  3. Select the Advanced tab.
  4. Press the Environment Variables button.
  5. In the System Variables section, select the Path variable in the list, then press the Edit button.
  6. Append the path to your MySQL Server bin directory (make sure to add a semi-colon after any existing items in the path before appending the new path). The default path for a 64-bit installation is C:\Program Files\MySQL\MySQL Server 5.7\bin.

Create Mattermost Database

Now that MySQL has been installed and configured, a database and user account must be provisioned for Mattermost to utilize.

  1. Open a command prompt and enter mysql -u root -p to connect to the MySQL server

  2. When prompted, enter the password created in step 9.a.

  3. At the mysql> prompt, execute the following commands to create the database and user account

    CREATE DATABASE mattermost;
CREATE USER mmuser IDENTIFIED BY 'mmuser-password';
GRANT ALL ON mattermost.* TO mmuser;
exit

  4. To confirm the database and user were configured correctly

    1. Connect to the MySQL server/datbase by executing mysql -u mmuser -p mattermost
    2. When prompted, entering mmuser-password
    3. If If successful, you will be at the mysql> prompt
    4. Type exit to finish

Set up Mattermost Server

  1. For the purposes of this guide we will assume this server has an IP address of 10.0.0.2

  2. Download the latest Mattermost Server by opening your favorite browser and navigating to https://releases.mattermost.com/X.X.X/mattermost-team-X.X.X-windows-amd64.zip where X.X.X is the latest Mattermost release version. For example, 3.4.0.

  3. Create the storage directory for files. We assume you will have attached a large drive for storage of images and files. For this setup we will assume the directory is located at c:\mattermost\data. Your directory structure should look similar to the image below.

    ../_images/windows_1_expected_directory_structure.png

  4. Configure Mattermost Server by editing the config.json file at c:\mattermost\config\config.json.

    • Update database name and server in the the connection string:
      • Old: "DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"
      • New: "DataSource": "mmuser:mmuser-password@tcp(10.0.0.1:3306)/mattermost?charset=utf8mb4,utf8"

    Note

    Optionally you may continue to edit configuration settings in config.json or use the System Console described in a later section to finish the configuration.

  5. Test the Mattermost Server

    1. Open a command prompt, and execute cd c:\mattermost\bin to change your working directory

    2. Execute mattermost.exe

    3. Verify that mattermost is running and connected to the database successfully by confirmed a console log like Server is listening on :8065 letting you know the service is running.

      ../_images/windows_2_platform_exe_test.png

    4. Stop the server by pressing CTRL+C

Configure the Firewall

Note

This is not required if you are installing on a single server.

  1. Open a command prompt as an administrator

  2. Execute the following command to allow inbound traffic to Mattermost

    netsh advfirewall firewall add rule name="Mattermost" dir=in action=allow program="C:\mattermost\bin\mattermost.exe" enable=yes

Establish a Windows Service

Establishing a windows service to supervise the Mattermost process is recommended to prevent the need to manually start/stop Mattermost. The included binary cannot be directly registered as a windows service; therefore, a wrapper-utility must be used.

  1. Download the latest version of NSSM (Non-Sucking Service Manager).

  2. From the downloaded zip-file, extract win64\nssm.exe to C:\mattermost\bin\

  3. Open a command line as an administrator

  4. To create the windows service, execute the following

    cd c:\mattermost\bin
nssm install mattermost c:\mattermost\bin\mattermost.exe
nssm set mattermost AppDirectory c:\mattermost

  5. Start the service by executing the following

    net start mattermost
tasklist /FI "IMAGENAME eq mattermost.exe"

Verify Mattermost Connectivity

To verify all steps executed thus far, we’ll attempt to access Mattermost through standard HTTP traffic. To perform this step, you’ll need access to a client machine with a compatible browser (e.g. Safari, Firefox, Edge, Chrome, etc).

  1. From a client workstation meeting the criteria above, launch your favorite web browser.

  2. Navigate to http://10.0.0.2:8065. If successful, you should reach an initialization web-page similar to the screenshot below.

    ../_images/windows_3_confirm_mattermost_browser.png

  3. Assuming your test was successful, close the browser as we’ll finish initializing Mattermost later in this guide.

Set up Web Proxy Server

A reverse proxy is recommended in order to provide:

  • SSL termination
  • HTTP to HTTPS redirection
  • Port mapping :80/:443 to :8065
  • Standard request logs
  • Load balancing (not described in this guide).

Internet Information Server (IIS) for Windows Server is the standard capability provided out-of-the-box that provides this function.

  1. For the purposes of this guide we will assume this server has an IP address of 10.0.0.3.
  2. Map a FQDN (fully qualitified domain name), like mattermost.example.com to the proxy server (e.g. 10.0.0.2).

Install IIS

  1. On the Start page, click the Server Manager tile, and then click OK.
  2. In Server Manager, select Dashboard, and click Add roles and features.
  3. In the Add Roles and Features Wizard, on the Before you begin page, click Next.
  4. On the Select installation type page, select Role-based or feature-based installation, and click Next.
  5. On the Select destination server page, select Select a server from the server pool, select your server, and click Next.
  6. On the Select server roles page, select Web Server (IIS).
  7. Expand Web Server (IIS) > Web Server > Application Development and select WebSockets Protocol, and then click Next.
  8. On the Add Roles and Features Wizard popup dialog, click Add Features, and then click Next.
  9. On the Select features page, click Next.
  10. On the Web Server Role (IIS) page, click Next.
  11. On the Select role services page, accept the default selections, and click Next.
  12. On the Summary of Features to Install page, click Install.
  13. On the Installation progress page, confirm that your installation of the Web Server (IIS) role and required role services completed successfully, and then click Close.
  14. To verify that IIS installed successfully, navigate to http://localhost in a web browser on the server, and confirm the default IIS Welcome page is displayed.

Configure Reverse Proxy

Reverse proxying involves rewriting an HTTP request and relaying it to a back-end server. IIS does not natively support this; however, Microsoft provides a URL Rewrite module and an Application Request Routing module which, when combined, are capable of performing these functions. We’ll start by installing these module, and then configure the proxy.

  1. Download the URL Rewrite 2.0 x64 module.

  2. Download the Application Request Routing 3.0 x64 module.

  3. Install the modules (trivial installers with no customizations or options to select).

  4. On the Start page, click the Server Manager tile, and then click OK.

  5. Expand the Tools menu, and select Information Information Services (IIS) Manager.

    ../_images/windows_4_IIS_manager.png

  6. In the left-hand navigation tree, expand the server node, expand Sites, and select Default Web Site.

  7. Double-click the URL Rewrite feature, as shown below.

    ../_images/windows_5_iis_manager_url_rewrite.png

  8. In the actions pane (far-right), select Add Rule(s)…

  9. Select Reverse Proxy and press OK.

  10. If prompted to enable proxy functionality, press OK.

  11. In the Add Reverse Proxy Rules dialog,

    1. Enter 10.0.0.2:8065 in the Enter the server name or IP address where HTTP requests will be forwarded field.
    2. Ensure the Enable SSL Offloading option is checked.
    3. Check Rewrite the domain names of the links in HTTP responses
    4. Enter 10.0.0.2:8065 in the From field.
    5. Enter mattermost.example.com in the To field.
    6. Press OK

  12. At this point, your configuration will relay all incoming traffic from http://mattermost.example.com to http://10.0.0.2:8065/. To confirm this, open your favorite browser and attempt to access http://mattermost.example.com, and upon success, you’ll see the Mattermost initialization screen.

Configure SSL

Note

SSL communication requires that the web server have a well-formed and trusted certificate. A common freely-available SSL encryption and certificate managemet is Let’s Encrypt; however, this service does not formally support the Windows Operating system. A number of third-parties have created clients to support this, and you are free to try out any of them. This section assumes that you have taken the necessary steps to obtain a web-server certificate that will be trusted by your users.

  1. Within the IIS Manager, select the server node in the left-hand connections pane.
  2. Double-click the Server Certificates option.
  3. Select Import… from the list of actions on the right-hand-side.
  4. Press the … button to locate your PFX formatted certificate.
  5. Enter the password to the certificate file.
  6. Select the Web Hosting certificate store, and press OK.
  7. In the left-hand navigation tree, expand the server node, expand Sites, and select Default Web Site.
  8. In the right-hand-side Actions pane, select Bindings….
  9. Press Add
  10. In the Add Site Binding dialog, Set the type to https and set the SSL Certificate to the certificate loaded previously. Press OK.

Redirect HTTP to HTTPS

  1. In the left-hand navigation tree, expand the server node, expand Sites and select Default Web Site.

  2. Double-click to open the Url Rewrite feature.

  3. In the actions-pane (far-right), select Add Rule(s)..

  4. Under the Inbound Rules section, select Blank rule and press OK.

  5. Populate the fields in the rule to match the screenshot below

    ../_images/windows_6_http_to_https_redirect.png

  6. Press Apply and then press Back to Rules.

  7. Ensure that the HTTP to HTTPS Redirect rule is at the top of the list of inbound rules. If nceessary, you can select a rule and use the Move Up and Move Down actions to reorganize.

  8. On a client workstation, open your favorite browser and navigate to http://mattermost.example.com and confirm that you are redirected to https://mattermost.example.com.

Finish Mattermost Server Setup

  1. Navigate to https://mattermost.example.com and create a user and team.

  2. The first user in the system is automatically granted the system_admin role, which gives you access to the System Console.

  3. From the town-square channel click the dropdown next to your team name and choose the System Console option

  4. Update General > Configuration settomgs in prior versions or Environment > Web Server in versions after 5.12 to properly configure your reverse proxy by entering https://mattermost.example.com as the Site URL

    Attention

    Failure to properly set the Site URL properly __will__ result in unexpected behavior.

  5. Update Notification > Email settings in prior versions or Authentication > SMTP in versions after 5.12 to setup an SMTP email service. The example below assumes AmazonSES.

    1. Set SMTP Username to [YOUR_SMTP_USERNAME]
    2. Set SMTP Password to [YOUR_SMTP_PASSWORD]
    3. Set SMTP Server to email-smtp.us-east-1.amazonaws.com
    4. Set SMTP Port to 465
    5. Set Connection Security to TLS
    6. Set Send Email Notifications to true (located at Site Configuration > Notifications in versions after 5.12)
    7. Set Notification Display Name to No-Reply (located at Site Configuration > Notifications in versions after 5.12)
    8. Set Notification From Address to mattermost@example.com (located at Site Configuration > Notifications in versions after 5.12)
    9. Set Require Email Verification to true (located at Authentication > Email in versions after 5.12)

  6. (Optional) Update Security > Sign Up settings in prior versions or Authentication > Signup in versions after 5.12:

    • Set Enable Email Invitations to true

  7. Update File > Storage settings in prior versions or Environment > File Storage in versions after 5.12:

    • Change Local Directory Location from ./data/ to /mattermost/data

  8. Update General > Logging settings:

    • Set Log to The Console to false

  9. Update Advanced > Rate Limiting settings in prior versions or Environment > Rate Limiting settings in versions after 5.12:

    • Set Vary By Remote Address to false
    • Set Vary By HTTP Header to X-Real-IP

  10. Feel free to modify other settings.

  11. Login to the Mattermost server (10.0.0.2) and restart the Mattermost Service by typing the following into a command line

net stop mattermost
net start mattermost