Configuring an IIS Frontend with DTS Tomcat Backend

Overview:

With this deployment, you would run IIS 7 as a typical frontline web server serving up CM1-generated HTML content, and then proxy the Ajax requests for dynamic DTS content locally from IIS to the DTS Tomcat using the Application Request Routing extension. This is what that server topology would look like:

The main benefit of this configuration comes in the fact that the majority of your site’s content would be served directly off of IIS 7, a popular platform that many server admins are comfortable maintaining. Additionally, upgrades to the DTS Tomcat – made available concurrently with new CM1 releases – would not require any downtime of your site’s main static content, as it would if you were to use the DTS Tomcat as your standalone web server.

The biggest downside of this configuration is that the Secure Sections feature in CM1 will not function. Secure Sections require a pure Tomcat environment to operate.

Prerequisites and considerations:

Before we begin implementing this setup, note that we are assuming that these basic prerequisites are already in place:

1. CM1 is installed and operational on your application server.
2. You have a site in CM1 with at least an “index” page at your site’s root that is in either the Pending or Live workflow state.
3. You have full access to configure and install applications on your production web server.

Table of Contents:

1. Install the DTS Tomcat
2. Install and configure IIS 7
3. Install Application Request Routing extension
4. Specify how CM1 and site visitors connect to DTS Tomcat
5. Create FTP user and setup CM1 publishing server definition
6. Open required ports
7. Operate the DTS Tomcat
8. Test and verify configuration
9. (Recommended) Create custom password for CM1 / DTS communication

1. Install the DTS Tomcat:

Follow the steps in the document below to download and install the DTS Tomcat on your production web server.

Install DTS Tomcat

You will want to configure the application to run as a service so that it won’t be tied to an application window. Follow these steps to do this:

1. Open a Command Prompt as an administrator.
2. Navigate to the <dts_root>\Deployment\Server\bin directory.
3. Run the command service.bat install

You should be prompted with a message indicating that the “Percussion DTS” service has been successfully installed.

2. Install and configure IIS 7:

Follow the instructions on the Microsoft TechNet website to install the latest version of IIS 7:

http://technet.microsoft.com/en-us/library/cc731179.aspx

If you already have IIS installed on your web server, note that you must run IIS version 7.0 or later in order to use the Application Request Routing extension, which is required to proxy DTS requests.

2.1 Setup your website in IIS:

You can setup your CM1 site the same as you would for any basic website in IIS, pointing to a Physical path that will contain typical static web files like HTML, CSS, and JavaScript. This document outlines the overall process:

http://technet.microsoft.com/en-us/library/cc772350%28v=ws.10%29.aspx

Take careful note of the Physical path you elect to use for your site, as in section 5 (“Create FTP user and setup CM1 publishing server definition”) of this document you will need to create an FTP user that can create content in this same directory.

Note: Depending on where and how your existing site is setup, it might make sense to add an alternate hostname or IP address binding to your IIS web site for QA testing before going live with your CM1 site. This could be either the server’s IP address or a temporary sub domain (such as cm1-web.percussion.com) that you would assign to the server. This way, you – and anyone else tasked with QA testing your new CM1 site – will be able to access the published site over an IP address or temporary sub-domain without disrupting your existing site, and test how your site displays and behaves in a live environment before making the switch.

2.2 Add HTML MIME type for files without an extension:

By default, CM1 publishes your site’s HTML content without an .html extension. When you navigate to these IIS-hosted pages from a browser, you will see either plain HTML code or a 404.3 Not Found error page unless you have mapped files without an extension to load as HTML.

To do this, open up IIS Manager, select your CM1 web site, and double click on the MIME Types icon. In the MIME Types menu, under Actions, select Add. Add a new MIME type with the following values:

File name extension: *

MIME type: text/html

Note: In some versions of IIS 7, a single period (.) may need to be used instead of an asterisk (*) for the wildcard filename extension. More info on adding MIME types in IIS can be found here:

http://technet.microsoft.com/en-us/library/cc725608%28WS.10%29.aspx

2.3 Change the Default Document to “index” without an extension:

Because CM1 doesn’t publish its pages with an extension, directory index pages in CM1 will publish as index rather than index.html. As a result, IIS won’t know what file to load as the default file when a site visitor accesses a directory on your server.

To correct this, again open up IIS Manager and select your CM1 web site, and then double click on the Default Document icon. Under Actions, select Add, and add a new entry as follows:

            Name: index

3. Install Application Request Routing extension:

You can find and install the Application Request Routing extension through this URL:

http://www.iis.net/downloads/microsoft/application-request-routing

You will likely need to restart IIS Manager to complete the installation. Note: it may also be necessary to install the URL rewrite extension as well. This can be found here: http://www.iis.net/downloads/microsoft/url-rewrite. 

3.1 Enable proxy and setup proxy rules:

In the following section (“Specify how CM1 and site visitors connect to DTS Tomcat”), we will configure CM1 so that the hardcoded Ajax requests for DTS content – present in your site’s published HTML pages – will point directly back to IIS over port 80. Because the DTS web services are only accessible and functional on your DTS Tomcat, which by default runs on port 9980, these requests will need to be rerouted from IIS to the DTS Tomcat using proxy rules.

First you will need to enable proxy functionality. To do this, select your root IIS site in the IIS Manager and double click on the new Application Request Routing Cache icon. Under Actions, select Server Proxy Settings, and then check off the Enable proxy option.

Next, we will add in the proxy rules themselves. The rules can be setup either at the root level of IIS so that they apply for all sites in IIS, or they can be configured for only your CM1 site to ensure that the rules don’t interfere with any non-CM1 sites contained within your instance of IIS. Based on which of these two options you choose, you’ll want to select either the root IIS site or your CM1 site itself, and then double-click on the URL Rewrite icon. From there, under Actions, select Add Rule(s).

You’ll want to add a blank rule where these three fields are inputted as follows:

Name:              Feed Services

Pattern:            feeds(.*)

Rewrite URL:     http://localhost:9980/feeds{R:1}

Note that the default port is actually 9970 for Staging. All other fields can be left at their default values. The completed rule should appear like this:

Once this is filled out, select Apply and then Back to Rules.

You will need to repeat this process seven times in total (six more times, following the completion of the rule above) in order for all of CM1’s Delivery Tier Services to proxy properly. Here are the values for all seven proxy rules:

Name:              Feed Services

Pattern:            feeds(.*)

Rewrite URL:     http://localhost:9980/feeds{R:1}

Name:              Dynamic Indexing Services

Pattern:            perc-metadata-services(.*)

Rewrite URL:     http://localhost:9980/perc-metadata-services{R:1}

Name:              Form Processing

Pattern:            perc-form-processor(.*)

Rewrite URL:     http://localhost:9980/perc-form-processor{R:1}

Name:              Comments and Likes

Pattern:            perc-comments-services(.*)

Rewrite URL:     http://localhost:9980/perc-comments-services{R:1}

Name:              Common UI

Pattern:            perc-common-ui(.*)

Rewrite URL:     http://localhost:9980/perc-common-ui{R:1}

Name:              Membership Services

Pattern:            perc-membership-services(.*)

Rewrite URL:     http://localhost:9980/perc-membership-services{R:1}

Name:              Polls

Pattern:            perc-polls-services(.*)

Rewrite URL:     http://localhost:9980/perc-polls-services{R:1}

Once all of these rules have been applied, your URL Rewrite menu should be populated like this (for a Production environment):

You will want to restart your root IIS site for these changes to take effect.

For secure https site configuration IIS SSL off loading need to be configured.  SSL Offloading in IIS

4. Specify how CM1 and site visitors connect to DTS Tomcat:

Note: There are specific instructions in addition to this section for adding a Staging DTS. 

In order for CM1 to write and retrieve content from your DTS database (e.g. write out page meta-data for Auto-lists, retrieve content submitted through Forms widgets, etc.), CM1 will need to be properly configured to interact with your production DTS Tomcat server.

These configuration changes will be made through your delivery-servers.xml file, which is located on your CM1 application server at <cm1_root>\rxconfig\DeliveryServer.

In that file you will find two DeliveryServer elements. The first one, by default, will reference http://localhost, while the second will reference https://delivery.percussion.com. This second we will leave untouched as it is used for production activation and license monitoring purposes. The first DeliveryServer element is the one we will need to modify.

By default, this first DeliveryServer element should look like this:

<DeliveryServer>

  <connection-url>http://localhost:9980</connection-url>

   <user>ps_manager</user>

   <password encrypted="true">-7a817995ebf59950e59a1641964fdd61</password>

   <admin-connection-url>https://localhost:8443</admin-connection-url>

   <allow-self-signed-certificate>true</allow-self-signed-certificate>

   <availableServices>

      <service>perc-form-processor</service>

      <service>feeds</service>

      <service>perc-comments-services</service>

      <service>perc-metadata-services</service>

      <service>perc-membership-services</service>

   </availableServices>

</DeliveryServer>

We will need to edit two child elements, connection-url and admin-connection-url.

The connection-url element is not used by CM1 for connection purposes, but rather it dictates the root DTS Tomcat domain that gets hardcoded into URLs on your published HTML pages. E.g. for Ajax requests to your DTS database, a URL such as http://www.percussion.com/perc-metadata-services/metadata/get will be coded into your published pages, where the base http://www.percussion.com portion of that URL would come from your connection-url. As connections to this URL will be coming from your site’s visitors, the URL will need to be public facing.

This should almost always be set to the main domain name specified in your CM1 site’s bindings, such as http://www.percussion.com.

Note: If you will be testing your site using an optional additional IP address or temporary sub-domain binding, you will want to change the value in your connection-url to match that IP or hostname during this testing period.

The admin-connection-url element is the URL that CM1 uses to make connections to your DTS Tomcat server’s SSL port, 8443 (9443 for Staging). This URL will only be used by the CM1 application. This is often set to a private IP address or hostname that only the CM1 application server is able to reach your production web server over. Whatever hostname you use, this URL will need to use the HTTPS protocol and specify the default DTS Tomcat SSL port of 8443, for example https://webserver.percussion.local:8443.

A delivery-servers.xml file configured to point to your production web server environment should look something like this:

<DeliveryServer>

  <connection-url>http://www.percussion.com</connection-url>

   <user>ps_manager</user>

   <password encrypted="true">-7a817995ebf59950e59a1641964fdd61</password>

   <admin-connection-url>https://webserver.percussion.local:8443</admin-connection-url>

   <allow-self-signed-certificate>true</allow-self-signed-certificate>

   <availableServices>

      <service>perc-form-processor</service>

      <service>feeds</service>

      <service>perc-comments-services</service>

      <service>perc-metadata-services</service>

      <service>perc-membership-services</service>

   </availableServices>

</DeliveryServer>

Note that the default DTS ports, 9980, can now be removed from the connection-url because we have configured proxy rules rerouting DTS requests internally from 80 to port 9980.

For any of the changes in this file to take effect, CM1 will need to be restarted. For changes to your connection-url value to take effect, a full site publish will need to be performed.

It is also recommended to that you change the default DTS Tomcat password in this configuration file. Please reference section 9 (“Create custom password for CM1 / DTS communication”) for instructions on how to do this.

5. Create FTP user and setup CM1 publishing server definition:

The process for creating an FTP user varies widely based on what FTP server software you elect to use. As such, this section will only outline the high-level requirements.

In section 2.1 (“Setup your website in IIS”) we instructed you to take careful note of the Physical path you elected to use for your site, because now you will need to create an FTP user that uses this exact same directory as its home or root directory. Naturally, this user will require full permissions to write and remove files and folders in this directory.

5.1 Setup CM1 FTP publishing server definition:

Please follow the directions here for setting up FTP server definitions:

Setup FTP Publishing

The options are well outlined in that doc, but three important points should be clarified for this type of deployment:

1. Folder Location: If you configured your FTP user’s home or root directory as outlined above (where your IIS site’s Physical path and your FTP user’s home directory are the same), you should simply use a single forward slash (“/”) in this field.
2. Ensure that you deselect the “Use Percussion web server setup” option. This option is only used when publishing to a standalone Tomcat web server.
3. Ensure that the “Set as Publish Now Server” checkbox is selected. Along with making this the server that content gets published to when an Admin elects to individually publish a page, this also ensures that meta-data information gets written out to your DTS Tomcat’s database when you publish your site using this publishing server definition.

6. Open required ports:

As outlined in the diagram at the beginning of this document, in order for CM1 to publish out all of your site’s content, two ports will need to be opened through your software and hardware firewalls between the CM1 application server and your production web server.

1. The CM1 application server will need to make outbound connections over port 8443/9443 to your production web server. This is used for CM1 to write and retrieve content from your DTS database.
2. The CM1 application server will need to make outbound connections over your FTP or SFTP port, 21 or 22 by default, to your production web server. This is so CM1 can transfer HTML files and other resources (CSS, image, JavaScript, etc. files) to your site’s root folder on your web server’s file system.

Note: depending on what FTP server software you use and your existing firewall rules, you may also have to configure your firewall to allow your FTP server to use a passive port range, or the Windows TCP/IP dynamic port range.

6.1 Verify ports:

After opening the required ports through your firewall, it is a good practice to use a tool such as telnet to verify that your changes have taken effect before proceeding. First, ensure that your CM1 application server has the telnet client installed (which is an optional feature for Windows Servers that can be added through the Server Manager application).

From the CM1 application server, run this command from a command prompt:

telnet {admin-connection-url} 8443

Note: (Use 9443 for Staging)

Where {admin-connection-url} matches the hostname in the admin-connection-url element identified in the above section (e.g. webserver.percussion.local). Next, run:

telnet {web_server_hostname} {ftp_port}

Where {web_server_hostname} and {ftp_port} matches your FTP server setup.

If both connections are successful, they should process immediately, and you will be faced with a blank screen with a blinking cursor. If the connection is being blocked by your firewall, you will receive a time-out error message.

7. Operate the DTS Tomcat:

Assuming you have followed the steps in section 1 of this document to install the DTS Tomcat service, use this procedure to start and stop the DTS Tomcat:

Start the DTS Tomcat by starting the “Percussion DTS” service in Windows Services.

Stop the DTS Tomcat by stopping the “Percussion DTS” service.

8. Test and verify configuration

At this point, all of the pieces should be in place for CM1 to publish your site to a fully functional IIS 7 frontend and DTS Tomcat backend web server environment.

With both your IIS web server and your DTS Tomcat server up and running, the first step towards confirming this will be to a run a full publish of your site using the FTP server definition we configured in step 5.1 (“Setup CM1 FTP publishing server definition”). Use the Reports tab in the Admin > Publish section of CM1 to monitor the progress of your publish operation, and to confirm that it completes without any failures.

Once the FTP publish operation completes, you should see your site’s content populated in the folder on your web server’s file system that has been specified as both your FTP user’s home directory and your IIS site’s physical path.

You now should be able to access your site’s content through any web browser using the hostname bound to your IIS CM1 site. Depending on where and how your existing site is setup, you may need to access your CM1 site for testing using the optional additional IP address or sub-domain binding, as mentioned in section 2.1.

Once you’ve confirmed that all of your static content appears as expected, you’ll want to navigate to the URLs below to ensure that your proxy rules are all working. Note that, besides the two noted exceptions, these addresses should return an XML file.

http://{hostname}/feeds/application.wadl

http://{hostname}/perc-metadata-services/application.wadl

http://{hostname}/perc-form-processor/ (will return Tomcat 404 page)

http://{hostname}/perc-comments-services/application.wadl

http://{hostname}/perc-common-ui/ (will return Tomcat 404 page)

http://{hostname}/perc-polls-services/application.wadl

http://{hostname}/perc-membership-services/application.wadl

Once you’ve ensured that everything appears and is functioning as expected, you are now free to make the switch (be it DNS change, site binding change, etc.) enabling your CM1 site as your live site.

9. (Recommended) Create custom password for CM1 / DTS communication:

Out-of-box, CM1 is configured to connect to your Tomcat using the username “ps_manager” and a default encrypted password. For security reasons, it is recommended to encrypt a new password for this user on both the CM1 and the DTS Tomcat end. To encrypt a new password for the ps_manager user on the Tomcat end, follow the steps below.

Note that some special characters in your new password string, such as “!” or “&”, can cause issues and should be avoided.

Open up a command prompt and navigate to the <dts_root>\JRE\bin directory. Once there, run this command (ensuring that the full command exists on one line):

java -classpath ../../Deployment/Server/lib/catalina.jar;../../Deployment/Server/bin/tomcat-juli.jar;../../Deployment/Server/lib/servlet-api.jar org.apache.catalina.realm.RealmBase -a sha mypassword

Where mypassword would be replaced by the new password you have chosen for your Tomcat user.

9.1 Copy encrypted password into Tomcat users configuration file:

The output of the above command should look like this:

mypassword:91dfd9ddb4198affc5c194cd8ce6d338fde470e2

In this example, copy out the 91dfd9ddb4198affc5c194cd8ce6d338fde470e2 portion, which is the encrypted version of mypassword.

Next, open up your tomcat-users.xml file located at <dts_root>\Deployment\Server\conf and find the line that reads:

<user username="ps_manager" password="f2c57870308dc87f432e5912d4de6f8e322721ba" roles="deliverymanager" />

Replace the existing encrypted password attribute value with the new encrypted password, like so:

<user username="ps_manager" password="91dfd9ddb4198affc5c194cd8ce6d338fde470e2" roles="deliverymanager" />

Note that you will need to restart your DTS Tomcat for these changes to be applied.

9.2 Ensure that CM1 knows this new Tomcat user password:

Now that your ps_manager user password has been changed on the Tomcat end, you will need to update CM1 to reflect this change as well, or else publishing will complete with failures and complain about invalid delivery server credentials.

To do this, open up your delivery-servers.xml file located at <cm1_root>\rxconfig\DeliveryServer and look for this line:

<password encrypted="true">-7a817995ebf59950e59a1641964fdd61</password>

Change the encrypted value to false, and replace the existing encrypted password with the plaintext version of your new Tomcat user password, like so:

<password encrypted="false">mypassword</password>

Next, shutdown and then start CM1 back up. Once you’ve done so, your new Tomcat user password will become encrypted on the CM1 end, and, if all of the steps above were followed correctly, your publishing operations should complete without any delivery server errors.