Installation and Administration

Internet Information Services (IIS) Configuration

Updated: October 16, 2020

This documentation is a draft version as it was never tested in production. Please give us feedback, we will take care of your questions about this configuration. You can also share configuration improvements with the community on answers.nuxeo.com.

This documentation gives you the guidelines to install a Nuxeo instance on a Windows Server and use IIS as a frontal web server. This documentation is more focused on the IIS configuration. For more details about the installation of the Nuxeo Platform or IIS, please refer to the relevant documentation.

Requirements:

  • Windows 2008 or greater,
  • Java 6 or above (for Nuxeo 5.6) and Java 7 or above (for Nuxeo 5.7.1 and greater),
  • IIS 7 or above with ASP.NET role service enabled,
  • Nuxeo 5.6 or greater installed.

Configuration

Nuxeo Installation

  1. Check Java is correctly installed.
  2. Download the Nuxeo Windows distribution (.exe).
  3. Install the Nuxeo Platform.
  4. Start the Nuxeo instance.
  5. Open the Browser from the Windows Server (firewalls must be enabled) at the address http://NUXEO_SERVER/nuxeo.
  6. Configure the server, but in General Settings, replace IP Address 0.0.0.0 by 127.0.0.1 to limit Tomcat to local answers.

Enabling Web Server (IIS)

  1. Connect as Administrator on the Windows Server.
  2. In the Server Manager, click on Add Roles and Features.
  3. Select Web Server (IIS).
  4. Leave the default configuration and validate.

Activating the Application Request Routing Add-On

  1. Download the "Application Request Routing" addon.
  2. Run the command:

    net stop was /y
    

    It might not be started, so ignore errors here.

  3. Run the command:

    net stop wmsvc /y
    

    It might not be started, so ignore errors here.

  4. Execute the downloaded .exe file and accept the default configuration.

If you have errors during the "Application Request Routing" installation

  • Check that Windows Service Pack is up-to-date (Start > Settings > Control Panel > Automatic Updates).
  • Also check the requirements (Windows version, etc.).

Configuring IIS

Enabling the Rewrite Feature

  1. Go into the Administration Tools panel.
  2. Open Internet Information Service (IIS) Manager.
  3. Select the local server node on the left panel.
  4. Click on "Application Request Routing" and open the feature.
  5. Edit the server proxy settings:

    1. Check the "Enable Proxy" box.
    2. Leave the default values.
  6. Save the configuration.

Adding the Rewrite Rule

  1. In Internet Information Service (IIS) Manager, select a server node on the left panel.
  2. Open URL Rewrite.
  3. Click on Add a rule(s)….
  4. Select Inbound rule > Blank rule. In the following steps, if a field is not specified, leave the default value.
  5. In Match URL:

    • Name: Nuxeo Inbound
    • Request URL: Match the pattern
    • Pattern: (nuxeo.*)
  6. In Server Variables:

    • Server Variable Name: HTTP_NUXEO_VIRTUAL_HOST
    • Value: {HTTP_HOST}
    • Check the box.
  7. In Action:

    • Action type: Rewrite
    • http://127.0.0.1:8080/{R:1}

If your Nuxeo server is not hosted by the IIS server, replace 127.0.0.1 by the internal IP address of the Nuxeo server. Of course, IIS server must reach this internal IP Address.

Preserving the Host Header

We've had report that the following is needed as well:

appcmd.exe set config -section:system.webServer/proxy -preserveHostHeader:true

Enhancing the URL MAX Length Parameter

Windows Web Server defines a default limit for URL paramaters. This limit is set to 256 characters. In Nuxeo, parameter length can be greater than this default value.

  1. Open the Window registry: Command + R, and type regedit.
  2. Open HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters.
  3. Right-click on Parameters > New > DWORD.

    • Name: UrlSegmentMaxLength
    • Value: 2048
    • Base: Decimal
  4. Restart the server.

Testing Your Configuration

We suggest to use a client desktop with Firefox and Firebug installed.

  1. Open Firebug.
  2. In Firebug, click on the Net section.
  3. Enable the Net feedback.
  4. Go to http://iis.servername/nuxeo, where iis.servername is the name of the server the client can reach.
  5. Connect as Administrator to Nuxeo. Each line displayed is a request made by the browser.
  6. Check that each line points to the iis.servername and not the 127.0.0.1 address without error (no red lines).

If you have errors, please check the next section.

Typical Errors

Error 1

502 - Web server received an invalid response while acting as a gateway or proxy server.

There is a problem with the page you are looking for, and it cannot be displayed. When the web server (while acting as a gateway or proxy) contacted the upstream content server, it received an invalid response from the content server.

In the rule you defined the target is http://internal.address.ip:8080. This error might occur because the server can't reach this address.

Error 2

500 - Internal server error.

There is a problem with the resource you are looking for, and it cannot be displayed.

This error means you made a mistake during the rule configuration and about the server variable name.

Error 3

If Nuxeo has a strange behavior, for instance:

  • you can't write in a text field,
  • every time you try to type something into a text field, the focus changes to the search field,
  • the Home Dashboard is empty
  • etc…

These problems may occur because you didn't enhance the URL MAX Length parameter.

You can look into your firebug if some requests returned a 401, with a "bad url" message.