Microsoft Windows

Last update: Download PDF Edit

1 Introduction

This document describes the installation and configuration of the Mendix software on a system running Microsoft (MS) Windows. It covers:

  • Installing the Mendix Service Console
  • Deploying a Mendix app
  • Configuring the MS Internet Information Services (IIS) server

2 Prerequisites

To set up an environment to run Mendix applications, you will need to install the Mendix software. For each Mendix application that will be run, a separate user (service) account is required. This section presents an overview of the setup.

Before starting this how-to, make sure you have the following prerequisites:

  • MS Windows 2008 SP2 or higher

  • .NET 4.5 or higher

  • IIS 7 or higher with the following service roles enabled:

    • IIS Management console

    • Static content

    • ASP.NET

  • MS Application Request Routing (ARR) installed (for more information, see Microsoft Application Request Routing)

  • Java Runtime 8, or other version depending on your Mendix Server Distribution. For example:

    • Mendix Server Distribution 4 requires Java 6

    • Mendix Server Distribution 5 requires Java 7

  • The Mendix Deployment Archive (MDA) of your Mendix project

  • The Mendix server distribution corresponding with your Modeler (see the Mendix App Store)

  • A database with sufficient security rights

    • Suitable database servers are IBM DB2, MariaDB, MS SQL Server, MySQL, Oracle Database and PostgreSQL. See System Requirements for more information
  • A local or domain user with the “log on as a service” local security policy set

3 Installing the Mendix Service Console

To download and install the Mendix Service Console, follow these steps:

  1. Download the latest version of the Mendix Service Console by following the Related downloads link from the Desktop Modeler Download Page of the App Store.

  2. Install the Mendix Service Console by following the installation wizard.

  3. Start the Mendix Service Console after the installation; the first time you launch the application, the Preferences dialog box will be shown (it will always be shown if no valid location is configured for the apps and server files).

  4. In the Preferences dialog box, enter a Location of apps and server files. This location is used for storing your app files and Mendix server files. Mendix recommends using a directory that is:

    • NOT on the system partition

    • where you can easily control the security rights

    The app directory consists of four sub-directories:

    • Backup – this directory stores any database changes due to model upgrades

    • Log – this directory stores all of the application log files

    • Project – this directory contains all of your application files; within this directory you will find the directory data/files that contain all of your uploaded files

    • Service – this directory contains files for configuring the Windows Services

    In addition, there will be a file called Settings.yaml that contains your application configuration.

4 Deploying a Mendix App

To deploy a Mendix app using the Mendix Service Console, follow these steps:

  1. Start the Mendix Service Console.

  2. Click Add app to add a new app. A wizard will appear for configuring the new app.

  3. Configure the Service Settings as follows:

    • Service name – this name must be unique within all existing Windows services

    • Display name – this is the description of the app, which is visible as a tooltip for the app in the left bar of the Mendix Service Console or as a column in the list of Windows services

    • Description – enter a description for the application that will be visible in the Mendix Service Console

    • Startup type – select whether you want the app to be started automatically when the server starts, started with a delay, started manually, or disabled altogether

    • User name and Password – the app will always run under the user account given here, and the service will be installed with this user account configured (for more information, see Prerequisites)

  4. Click Next.

  5. On the Project Files screen, click Select app….

  6. Now select the MDA file that was created in the Modeler and contains your application logic. After the installation of your MDA file, you will see which Mendix server (Mendix runtime) version is needed.

  7. Configure the Database Settings:

    • Type – the database server type

    • Host – the IP address or host name of the database server

    • Name – the database name

    • User name and Password – the database user name and password

  8. Click Next.

  9. On the Common Configuration screen, keep the default settings. These settings should only be changed if this is needed for your application setup.

  10. Click Finish and start the application.

5 Configuring the Microsoft Internet Information Services Server

To configure the MS IIS server, follow the steps in the sections below.

5.1 Activating a Proxy in ARR

In order to use the proxy functionality within ARR, you need to enable this feature within IIS. To activate a proxy in ARR, follow these steps:

  1. Start the IIS Manager.
  2. Select the Server in the Connections pane.
  3. Open the Application Request Routing feature.
  4. Click Server Proxy Settings in the Actions pane on the right side of the screen.
  5. Select Enable proxy and click Apply in the Actions pane.

5.2 Creating a Website

To create a website, follow these steps:

  1. Open the IIS Manager.

  2. In the Connections pane, right-click the Sites node in the tree and select Add Web Site.

  3. In the Add Web Site dialog box, enter a friendly name for your web site in the Web site name field.

  4. In the Physical path field, enter the physical path of your application-project-web folder (for example, D:\Mendix\Apps\Application\Project\Web).

  5. Select the Protocol for the website from the Type list.

  6. The default value in the IP address box field is All Unassigned. If you must specify a static IP address for the website, enter the address in the IP address box.

  7. Enter a port number in the Port field.

  8. Click OK.

5.3 Configuring the MIME Types

To configure the MIME types, follow these steps:

  1. Open the IIS Manager and navigate to the website you want to manage.

  2. In the Features View, double-click MIME Types.

  3. In the Actions pane, click Add.

  4. In the Add MIME Type dialog box, add this file type:

    • File name extension: .mxf
    • MIME type: text/xml
  5. Add another MIME type:

    • File name extension: .json
    • MIME type: application/json
  6. Click OK.

5.4 Configuring the URL Rewrite

5.4.1 Reverse Proxy Inbound Rules

You need to add a number of rules to configure the following request handlers.

Rule Name Pattern Rewrite URL
1 xas ^(xas/)(.*) http://localhost:8080/{R:1}{R:2}
2 ws ^(ws/)(.*) http://localhost:8080/{R:1}{R:2}
3 ws-doc ^(ws-doc/)(.*) http://localhost:8080/{R:1}{R:2}
4 ws-file ^(file)(.*) http://localhost:8080/{R:1}{R:2}
5 link ^(link/)(.*) http://localhost:8080/{R:1}{R:2}

Follow the instructions below and replace [Name] with the name of the rule in the table above, [Pattern] with the regular expression pattern, and [Rewrite URL] with the Rewrite URL. Note that some patterns contain a trailing slash, /, when they need to point to an exact path (for example, /ws-doc/mydoc/1234).

  1. Open the IIS Manager and navigate to the website you want to manage.

  2. In the Features View, double-click URL Rewrite.

  3. In the Actions pane on the right side of the screen, click Add rule(s)… to add a new rewrite rule.

  4. In the Inbound Rules field, enter localhost:8080, then click OK.

  5. Select ReverseProxyInboundRule1 in Features View.

  6. In the Actions pane on the right side of the screen, click Rename.

  7. Rename ReverseProxyInboundRule1 to [Name].

  8. Double-click [Name] in Features View to change the properties of your rule.

  9. In the Pattern field enter [Pattern].

  10. In the Rewrite URL field, enter [Rewrite URL] (in the rules above this is always http://localhost:8080/{R:1}{R:2}).

  11. Click Apply.

  12. Click Back to Rules.

  13. Repeat from step 3 to add all the required rules.

You can also add additional request handlers in the same way. However you must ensure that they come after the rule add x-forwarded-proto header, described below.

5.4.2 Rule add x-forwarded-proto header

This is required to ensure that you can access the Swagger documentation of your published REST services. It has to be the first rule; it is described last to ensure that it is moved to the top and that additional rules are not placed above it accidentally.

  1. Click View Server Variables

  2. Check if server variable HTTP_X_FORWARDED_PROTO is listed. If it is, skip to step 7.

  3. In the Action page, click Add to add the server variable.

  4. Enter the Server variable name HTTP_X_FORWARDED_PROTO.

  5. Click OK.

  6. Click Back to Rules

  7. Click Add rule(s)….

  8. Click Blank Rule.

  9. Set the Name to add x-forwarded-proto header.

  10. In the Match URL section, set Requested URL to Matches the Pattern.

  11. Set Using to Regular Expressions.

  12. Set the pattern to .*.

  13. Set Ignore Case to true (checked).

  14. In the Server Variables section, click Add.

  15. Select Server variable name HTTP_X_FORWARDED_PROTO

  16. Set Value to https.

  17. Click OK.

  18. In the Action section, select None.

  19. Set Stop processing of subsequent rules to false (unchecked).

  20. Click Apply in the Action pane to save the rule.

  21. Click Back to Rules.

  22. Select the newly created add x-forwarded-proto header rule and use the Move Up button in the Action pane to move the rule to the top of the list.

5.5 Disabling the Client Cache

In the application directory under Project/Web, you will find the web.config file that contains the MS IIS configuration for the application. You should add the following code to this file, between the <system.webServer></system.webServer> tags. :

<staticContent>
    <clientCache cacheControlMode="DisableCache" />
</staticContent>

Afterwards, the contents of this file will be similar to the following example:

web.config

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="add x-forwarded-proto header">
                    <match url=".*" />
                    <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />  <serverVariables>
                        <set name="HTTP_X_FORWARDED_PROTO" value="https" />
                    </serverVariables>
                    <action type="None" />
                </rule>
                <rule name="xas" stopProcessing="true">
                    <match url="^(xas/)(.*)" />
                    <action type="Rewrite" url="http://localhost:8080/{R:1}{R:2}" />
                </rule>
                <rule name="ws" stopProcessing="true">
                    <match url="^(ws/)(.*)" />
                    <action type="Rewrite" url="http://localhost:8080/{R:1}{R:2}" />
                </rule>
                <rule name="ws-doc" stopProcessing="true">
                    <match url="^(ws-doc/)(.*)" />
                    <action type="Rewrite" url="http://localhost:8080/{R:1}{R:2}" />
                </rule>
                <rule name="ws-file" stopProcessing="true">
                    <match url="^(file)(.*)" />
                    <action type="Rewrite" url="http://localhost:8080/{R:1}{R:2}" />
                </rule>
                <rule name="link" stopProcessing="true">
                    <match url="^(link/)(.*)" />
                    <action type="Rewrite" url="http://localhost:8080/{R:1}{R:2}" />
                </rule>
            </rules>
        </rewrite>
        <staticContent>
            <mimeMap fileExtension=".mxf" mimeType="text/xml" />
            <clientCache cacheControlMode="DisableCache" />
        </staticContent>
    </system.webServer>
</configuration>

6 Preserving the Host Header

To make sure the correct application root URL is used within your web services, you must make sure the host header contains the original host header from the client request. To make sure the host header is preserved, follow these steps.

  1. Click Start, and then click All Programs.

  2. Click Accessories, and then click Command Prompt.

  3. Execute the following command from the command prompt:

    cd %windir%\system32\inetsrv
    
  4. Enter:

    appcmd.exe set config -section:system.webServer/proxy /preserveHostHeader:"True" /commit:apphost
    

7 Troubleshooting

When configuring IIS it can seem like you have done everything right but it just doesn’t seem to work. This section describes a few common problems that people have run into when setting up IIS.

  1. When opening the website in the browser, an IIS error page regarding access permission is displayed.

    Validate your security settings. The user that runs the IIS service must be able to access the full directory path. (This is probably user: IIS_IUSRS, but confirm this in your service list). If your Mendix application is installed on “E:\Mendix\projects\MyApp” the IIS user must be able to read all the folders in the hierarchy (Mendix, projects, MyApp, and the web folder inside MyApp).

  2. I can see the login page in the browser, but when triggering an action I get a 404 or “server not found message”.

    • Did you have to enable or install additional plugins?

      If so, make sure to restart the entire IIS service. You can configure the newly installed settings, but they won’t have any effect until you restart the full IIS service.

    • Did you add new configuration settings, like the rewrite rule?

      Of course you did, but did you also restart the website? After adding new configuration options like the rewrite URL you need to restart the website. You can do this by right clicking on your newly created site and you should see a restart option.

  3. I can sign in, but when entering an invalid password my login page shows ‘server not found’ instead of invalid login.

    Some IIS installations hide the content of any response that isn’t HTTP status code 200-OK. If you enter invalid credentials during a Mendix login, Mendix returns a status code in the 400-range to indicate unauthorized access. This response also contains a JSON string with the response we want to show to the user.

    Mendix cannot work if IIS is hiding detailed error messages. You need to turn on ‘Detailed Error Messages’. The instruction on how to change this setting on your website can be found on the Microsoft website here: IIS7 : HOW TO enable the detailed error messages for the website while browsed from for the client browsers

  4. I’m still having issues finding the cause of my problems; what can I do?

    First assess whether you are hitting the Mendix application. If IIS forwards anything to the running Mendix app you can see that in the log. The log nodes ‘Connector’ and ‘Jetty’ can be most helpful. The Connector log node is able to print information about any incoming request. If you enable Trace logging you can see if the request comes in to the right request handler.

    If the ‘Connector’ doesn’t print anything you can also enable trace logging on ‘Jetty’. The ‘Jetty’ log node will print a message for every connection that is established with Mendix. If Jetty doesn’t print a trace message the IIS rewrite rules are definitely not setup correctly.

    If you do have information in the ‘Connector’ log node you can see where the requests are being forwarded to. This should help you understand where the rewrite rules are directing traffic and how to change it.

    When you have concluded that no messages are arriving at Mendix you can enable IIS trace logging. By doing this, every rewrite rule gets printed to an IIS trace log file; you can see exactly how IIS changes the request and where it is forwarded to. This should provide you with the information needed to change the rewrite rules to the correct configuration. https://docs.microsoft.com/en-us/iis/extensions/url-rewrite-module/using-failed-request-tracing-to-trace-rewrite-rules

See Troubleshooting IIS (Internet Information Services) for more troubleshooting information.