Configuring an Apache HTTPD Frontend with DTS Tomcat Backend

Overview:

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

$C:\fakepath\apacheproxy.png$

The main benefit of this configuration comes in the fact that the majority of your site’s content would be served directly off of Apache HTTPD, 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:

CM1 is installed and operational on your application server.
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.
You have full access to configure and install applications on your production web server.

Install the DTS Tomcat
Install and configure Apache HTTPD
Enable proxy modules and setup proxy rules
Specify how CM1 and site visitors connect to DTS Tomcat
Create FTP user and setup CM1 publishing server definition
Open required ports
Operate the DTS Tomcat
Test and verify configuration
(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. Ensure that you follow the proper steps depending on your production web server’s operating system:

Install DTS Tomcat

1.1 Setup Windows service (skip to step 2 if you’re using Linux):

If you are installing the DTS Tomcat on Windows Server, 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:

Open a Command Prompt as an administrator.
Navigate to the <dts_root>\Deployment\Server\bin directory.
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 Apache HTTPD:

Follow the instructions on the Apache website to download and install the latest version of Apache HTTPD:

http://httpd.apache.org/

If you already have an older version of Apache installed that you want to work with, note that any version that is compatible with the modules required to proxy DTS requests, mod_proxy, mod_proxy_http and mod_proxy_connect, should be sufficient. Most distributions of Apache HTTPD come with these modules out-of-box.

2.1 Setup virtual hosts:

You can setup your CM1 site’s virtual host the same as you would for any basic website, pointing to a document root that will contain typical static web files like HTML, CSS, and JavaScript. This document outlines the overall process (note that the steps will vary based on your version of Apache and your operating system):

http://httpd.apache.org/docs/2.2/vhosts/examples.html

Take careful note of the DocumentRoot 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 you existing site is setup, it might make sense to setup an additional virtual host for QA testing before going live with your CM1 site. This new virtual host would essentially be a duplicate of the primary one, with the difference being you would configure this to use 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 Change the default page type to HTML:

By default, CM1 publishes your site’s HTML content without an .html extension. When you navigate to these Apache-hosted pages from a browser, you will see plain HTML code unless your server’s default MIME type is set to HTML.

To make this change, open your Apache web server’s main configuration file (typically httpd.conf or apache2.conf) in a text editor, and find the line that begins with DefaultType. Change that line to read:

DefaultType text/html

2.3 Change the default index page 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, Apache 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 your Apache web server’s main configuration file (httpd.conf or apache2.conf) in a text editor and find the line that starts with DirectoryIndex. Change that line to read:

DirectoryIndex index index.html index.php

Note: In most Ubuntu distributions of Apache, this property will be found in your dir.conf file, located in your <apache_root>/mods-enabled/ directory.

3. Enable proxy modules and setup proxy rules:

The method to enable the required modules varies depending on your version of Apache and what operating system you are running. Typically, you will find a block of LoadModule lines in your main Apache configuration file (httpd.conf or apache2.conf). Three of these lines should reference the modules required to proxy DTS requests, mod_proxy, mod_proxy_http and mod_proxy_connect. Look for these lines and ensure that they are not commented-out with a preceding hash character (commented-out lines indicate disabled modules). The three relevant lines in this module block should look like this:

LoadModule proxy_module includes/mod_proxy.c

LoadModule proxy_http_module modules/mod_proxy_http.so

LoadModule proxy_connect_module modules/mod_proxy_connect.so

Note: In most Ubuntu distributions of Apache, modules can be enabled by creating a symbolic link in your <apache_root>/mods-enabled/ directory that points to the desired module in your <apache_root>/mods-available/ directory. This can be done manually, or by using the a2enmod command like so:

sudo a2enmod proxy proxy_http proxy_connect

3.1 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 Apache over port 80. Because the DTS web services are only accessible and functional on your DTS Tomcat, which by default runs on port 9980 (9970 for Staging), these requests will need to be rerouted from Apache to the DTS Tomcat using proxy rules.

With the proxy modules enabled, the required proxy rules can be placed within any actively referenced Apache configuration file. If you want these rules to be active for all sites hosted by this instance of Apache, you can place these rules in any logical location within your main Apache configuration file (httpd.conf or apache2.conf). Alternately, you can elect to drop this configuration set directly into your site’s virtual host so that these rules will be exclusive to your one site.

Here are the full proxy configuration rules that will need to be present in one of your Apache configuration files. Please note that these proxy rules point to "localhost". If the DTS Tomcat lives on another server, "localhost" will need to be replaced by either the DNS name of the DTS Server, or IP address of the DTS Server. Also note this example is for a standard Production DTS. A Staging DTS will use port 9970.

#Feed Services:

ProxyPass /feeds http://localhost:9980/feeds
ProxyPassReverse /feeds http://localhost:9980/feeds

#Dynamic Indexing Services

ProxyPass /perc-metadata-services http://localhost:9980/perc-metadata-services
ProxyPassReverse /perc-metadata-services http://localhost:9980/perc-metadata-services

#Form Processing

ProxyPass /perc-form-processor http://localhost:9980/perc-form-processor
ProxyPassReverse /perc-form-processor http://localhost:9980/perc-form-processor

#Comments and Likes

ProxyPass /perc-comments-services http://localhost:9980/perc-comments-services
ProxyPassReverse /perc-comments-services http://localhost:9980/perc-comments-services

#Common UI

ProxyPass /perc-common-ui http://localhost:9980/perc-common-ui
ProxyPassReverse /perc-common-ui http://localhost:9980/perc-common-ui

#Polls

ProxyPass /perc-polls-services http://localhost:9980/perc-polls-services
ProxyPassReverse /perc-polls-services http://localhost:9980/perc-polls-services

#Membership Services

ProxyPass /perc-membership-services http://localhost:9980/perc-membership-services
ProxyPassReverse /perc-membership-services http://localhost:9980/perc-membership-services

As with any changes made to your Apache configuration files, Apache will need to be restarted for any of these updates to take effect.

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:

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

<user>ps_manager</user>

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

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

<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 be the content of 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 site’s virtual host, such as http://www.percussion.com.

Note: If you will be testing your site using an optional additional virtual host that an IP address or a temporary sub-domain resolves to, 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. 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:

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

<user>ps_manager</user>

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

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

<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 your operating system and what FTP server software you elect to use. As such, this section will only outline the high-level requirements.

In section 2.1 (“Setup virtual hosts”) we instructed you to take careful note of the DocumentRoot 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:

Folder Location: If you configured your FTP user’s home or root directory as outlined above (where Apache’s document root and your FTP user’s home directory are the same), you should simply use a single forward slash (“/”) in this field.
Ensure that you deselect the “Use Percussion web server setup” option. This option is only used when publishing to a standalone Tomcat web server.
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.

The CM1 application server will need to make outbound connections over port 8443 (9443 for Staging) to your production web server. This is used for CM1 to write and retrieve content from your DTS database.
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 installed by default on most Linux machines, and is an optional feature for Windows Servers that can be easily added through the Server Manager application).

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

telnet {admin-connection-url} 8443

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:

7.1 Windows:

Assuming you have followed the steps in section 1.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.

7.2 Linux:

From a terminal window, navigate to the DTS Tomcat’s installation root directory and run this command to start the server:

nohup ./TomcatStartup.sh &

To stop the DTS, run:

./TomcatStartup.sh

Note that “nohup” and “&” can be used when running the startup script (as in the example above) to ensure that the process is not tied to your terminal window.

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 Apache frontend and DTS Tomcat backend web server environment.

With both your Apache 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 Apache server’s document root.

You now should be able to access your site’s content using the hostname specified in the virtual host definition you created for your 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 virtual host, 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

Once you’ve ensured that everything appears and is functioning as expected, you are now free to make the switch (be it DNS change, virtual host 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 based on your operating system.

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

9.1 Encrypt Tomcat user password in Windows:

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.2 Encrypt Tomcat user password in Linux:

Open up a terminal window 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.3 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:

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

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

9.4 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:

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 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.