Configuring IIS with JBoss

This topic explains how to configure the Microsoft IIS 7.5 Web Server for Appian when used with a supported JBoss application server version.

See also: System Requirements

Definitions

  • <JBOSS_HOME> refers to the JBoss installation directory.
  • <INSTALL_HOME> refers to the Appian installation directory.
  • <IIS_DOCUMENT_ROOT> refers to the document root directory for the IIS server (usually c:\inetpub\wwwroot).
  • <ISAPI_HOME> refers to the Jakarta ISAPI Redirector installation directory.
    • The default <ISAPI_HOME> location is C:\Redirector.
  • <SERVER_NAME> refers to the host name of the machine where IIS is installed.

Set Up JBoss

  1. Depending on whether the domain or standalone configuration is in use, edit one of the following files:
    • <JBOSS_HOME>\domain\configuration\domain.xml or <JBOSS_HOME>\standalone\configuration\standalone.xml
  2. Verify that the AJP connector is listed under the <subsystem xmlns="urn:jboss:domain:web:*" ...> element:
    • <connector name="ajp" protocol="AJP/1.3" scheme="http" socket-binding="ajp"/>
  3. Verify that port 8009 is bound to listen for AJP traffic under the <socket-binding-group name="standard-sockets" ...> element:
    • <socket-binding name="ajp" port="8009"/>

Set Up ISAPI Filter

  1. Download the 32-bit ISAPI Redirector DLL (isapi_redirector.dll), version 1.2.37 from Jakarta's Windows Connector downloads page.
    • The 32-bit ISAPI Redirector DLL is supported on 64-bit Windows using WoW64 mode.
    • At the time of writing these instructions, the most recent version is 1.2.37.
  2. Rename isapi_redirect-1.2.37.dll to isapi_redirect.dll.
  3. Create the <ISAPI_HOME> folder (ie. C:\Redirector).
  4. Create the following subfolders under <ISAPI_HOME>:
    • \ISAPI
    • \conf
    • \log
  5. Save the isapi_redirect.dll file in <ISAPI_HOME>\ISAPI.
  6. Create a text file with the name isapi_redirect.properties under the <ISAPI_HOME>\ISAPI folder using the following example settings:

    1
    2
    3
    4
    5
    6
    
     extension_uri=/Redirector/isapi_redirect.dll 
     log_file=<ISAPI_HOME>\Redirector\log\isapi_redirect.log 
     log_level=info 
     worker_file= <ISAPI_HOME>\Redirector\conf\workers.properties 
     worker_mount_file= <ISAPI_HOME>\Redirector\conf\uriworkermap.properties 
     strip_session=1
    
  7. Verify that there are no extra spaces after each line.
  8. Create a text file named uriworkermap.properties.
  9. Save this file in the <ISAPI_HOME>\conf folder.
  10. Add the following settings to the uriworkermap.properties file:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
     /suite|/*=wlb
     !/suite/*.jpg=wlb
     !/suite/*.gif=wlb
     !/suite/*.png=wlb
     !/suite/*.js=wlb
     !/suite/*.html=wlb
     !/suite/*.xml=wlb
     !/suite/*.css=wlb
     !/suite/*.xsl=wlb
     !/suite/*.ico=wlb
     !/suite/*.svg=wlb
     !/suite/*.gwt.rpc=wlb
     !/suite/*.htc=wlb
     /suite/s/*=wlb_jboss
     /suite/plugins/servlet/*=wlb_jboss
    
  11. Create a text file named workers.properties.
  12. Save it in the <ISAPI_HOME>\conf folder.
  13. Use the following example settings:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
     worker.list=wlb,wlb_jboss,jkstatus
      
     worker.ajp13w1.type=ajp13
     worker.ajp13w1.host=<app server 1 ip address>
     worker.ajp13w1.port=8009
    
     worker.ajp13w2.type=ajp13
     worker.ajp13w2.host=<app server 2 ip address>
     worker.ajp13w2.port=8009
      
     worker.wlb.type=lb
     worker.wlb.balance_workers=ajp13w1  
    
     worker.wlb_jboss.type=lb
     worker.wlb_jboss.balance_workers=ajp13w2  
      
     worker.jkstatus.type=status
     worker.wlb.sticky_session=1
    
    • NOTE: Even though we list two application servers in the above example, there is actually only one. Both ajp13w1/ajp13w2 configurations are necessary to ensure the correct uriworkermap.properties URL requests go to JBoss.
  14. Verify that your properties files use a .properties file extension, rather than .txt.
  15. Give the user (or system) account that is running IIS full control over the <ISAPI_HOME> folder.

Copy Static Resources to the Web Server

Since the Web server will be handling requests for static resources and forwarding all other requests to the application server, you need to copy over the static files that ship with Appian.

  1. Copy all of the files that match the static file extensions listed in the uriworkermap.properties example above from the <APPIAN_HOME>/ear/suite.ear/web.war directory to a new directory named suite in a location that will be read by the Web server.
    • For example <IIS_DOCUMENT_ROOT> may be used, so the files would be copied to <IIS_DOCUMENT_ROOT>/suite, preserving the same directory structure as is present inside <APPIAN_HOME>/ear/suite.ear/web.war.
    • If another directory is chosen, then a virtual directory mapping will need to be created (step 11 of the IIS Setup section that follows)
  2. If the web server is on a separate machine than the application server, a common configuration, these files will need to be copied to that location on the other machine.

Set Up IIS

  1. Ensure no other web server is listening on port 80 on your machine, such as an Apache server, either by turning them off via the Service menu or by changing the binding.
  2. Ensure IIS and other important features are turned on by completing the following:
    1. Open the Control Panel and select Programs > Programs and Features.
    2. Click Turn Windows Features on or off.
    3. Expand Internet Information Services >Web Management Tools.
    4. Ensure checkboxes for IIS Management Console, IIS Management Scripts and Tools, and IIS Management Service are checked.
    5. Expand World Wide Web Services > Common HTTP Features.
    6. Ensure Default Document, HTTP Redirection, and Static Content are checked.
    7. Within the same World Wide Web Services folder, ensure the Health and Diagnostic Folder is checked.
    8. Expand the Performance Features folder and ensure Static Content Compression is checked.
    9. Expand the Security folder and ensure Request Filtering is checked.
  3. Verify that the ISAPI Filter, CGI Features, and Request Filtering are installed by completing the following:
    1. Click Start > Control Panel.
    2. Type Turn Windows features on or off in the search field.
    3. Select the Turn Windows features on or off option in the control panel.
    4. Expand Internet Information Services > World Wide Web Services > Application Development Features.
    5. Make sure that the CGI checkbox, the ISAPI Extensions checkbox, and the ISAPI Filters checkbox are selected.
    6. Expand Internet Information Services > World Wide Web Services > Security.
    7. Make sure that the Request Filtering checkbox is selected.
  4. Click Administrative Tools from the Windows Control Panel.
  5. Select Internet Information Services (IIS) Manager.
  6. In the Features view, select the ISAPI and CGI Restrictions feature.
    1. Click Add to create a new ISAPI allowance.
    2. In the Executable field, type <ISAPI_HOME>\ISAPI\isapi_redirect.dll.
    3. Type Redirector in the Description field.
    4. Select the Allow extension path to execute checkbox.
    5. Click OK.
  7. In the Features view, select the Handler Mappings feature.
    1. On the Actions list, click Edit Feature Permissions.
    2. Select the Read, Script, and Execute checkboxes.
      • The ISAPI-dll and CGI-exe resources are listed as enabled.
    3. Back in the Handler Mappings feature, double-click ExtensionlessUrlHandler-Integrated-4.0.
    4. Click Request Restrictions.
    5. On the Verbs tab, enter GET, POST, PUT, DELETE, HEAD, OPTIONS, and CONNECT.
    6. Click OK.
  8. In the Features view, select ISAPI Filters.
    1. Click Add to create a new ISAPI filter.
    2. Set the filter name to Redirector.
    3. Set the Executable to <ISAPI_HOME>\ISAPI\isapi_redirect.dll.
    4. Click OK.
  9. In the left navigation, select Application Pools to display the available application pools.
    1. Select DefaultAppPool.
    2. In the Actions list, under Edit Application Pool, select Advanced Settings.
      • The Advanced Settings dialog box is displayed.
    3. In the General group, select Enable 32-Bit Applications.
    4. Select TRUE, then OK.
  10. In the left navigation, expand Sites and select Default Web Site.
    • If you've already created an application for use with Appian, select that website.
  11. With the Default Web Site selected, open the ISAPI Filters feature.
  12. Verify that the Redirector filter appears. If not, add it to the web site by completing the following:
    1. Click Add to create a new ISAPI filter.
    2. Set the filter name to Redirector.
    3. Set Executable to <ISAPI_HOME>\ISAPI\isapi_redirect.dll and click OK.
  13. Create a virtual directory for the redirector
    1. Select the Default Web Site node in the left navigation.
    2. On the Actions list, select View Virtual Directories.
    3. On the Actions list, click Add Virtual Directory.
    4. Type Redirector for the Alias.
    5. Type <ISAPI_HOME>\ISAPI for the Physical Path.
    6. Click Test Settings to verify that the necessary permissions are in place for the Redirector folder.
  14. Create a virtual directory for static content if not located in <IIS_DOCUMENT_ROOT> (omit these steps if appian static content is located in <IIS_DOCUMENT_ROOT>)
    1. Select the Default Web Site node in the left navigation.
    2. On the Actions list, select View Virtual Directories.
    3. On the Actions list, click Add Virtual Directory.
    4. Type suite in the Alias field.
    5. Type the directory where the static content is located (up to and including 'suite') for the Physical Path.
    6. Click OK.
  15. Turn off access to the Appian WEB-INF directory from the web server
    1. In the Features view, select the Request Filtering feature
    2. Under the URL tab, select Deny Sequence…
    3. Enter WEB-INF in the Deny Sequence textbox
    4. Click OK.
    5. Restart IIS by running the command prompt as an Administrator and entering iisreset.
    6. Test the filtering by attempting to navigate a browser to: http://<SERVER_NAME>/suite/WEB-INF/web.xml. Access should be denied.
  16. Ensure that static content compression is turned on to improve performance
    1. In the Features view, select the Compression feature.
    2. Make sure the Enable static content compression checkbox is checked
    3. Hit "Apply" under the Actions if the checkbox had to be selected
  17. (Optional) Redirect http://<SERVER_NAME> to the Appian login page by completing the following:
    1. Create a text file named index.htm in the <IIS_DOCUMENT_ROOT> directory.
    2. Paste the following HTML into your index.htm file.

      1
      2
      3
      4
      5
      6
      
      <html>
      <head>
      <title>Appian</title>
      <META HTTP-EQUIV="Refresh" CONTENT="0; URL=/suite">
      </head>
      </html>
      
    3. When the redirect is in place, requests sent to http://<SERVER_NAME> are redirected to the Appian start page.
FEEDBACK