Configuring a Standalone DTS Tomcat as a Production Web Server

Overview:

Of the three primary server deployment models outlined in the Production Web Server Setup document, the most basic approach would be to publish your website to a server running a standalone DTS Tomcat web server. That way, both static HTML content and dynamic DTS content would be served off of the same web server. The server topology here would look like this:

$C:\fakepath\standalonetomcat.png$

The major benefit of this configuration is its simplicity. With a standalone DTS Tomcat, there is no need for a dual server deployment with the accompanying internal proxy configuration. This means less moving parts to maintain and manage.

While Tomcat is a popular application server – it comes with a fully functional HTTP server component, some people still prefer to go with a more robust HTTP server, such as Apache HTTPD or IIS, as their frontline web server. It is important to note that if you plan to use the supplied version of Tomcat as your web server, it should be security hardened in the same way as you would any other web server.

Additionally, considerations such as compatibility with certain server-side scripting languages, as well as lack of certain modules and extensions available for Apache HTTPD and IIS, should to be taken into account before selecting the DTS Tomcat as your frontline web server.

The main drawback of this configuration is that upgrades to your DTS Tomcat – released concurrently with new CM1 versions – will require brief downtime of your live site, typically no more than five minutes.

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.

Note: This document assumes that your existing site (if applicable) is currently running on a separate machine from the production web server that we will be configuring. If you are installing and configuring the DTS Tomcat on the same machine as your existing web server, you will have to manage the availability of HTTP and HTTPS ports 80 and 443 accordingly when you cut over from your existing web server to your new DTS Tomcat server, and you can ignore all steps relating to DNS switchover.

Install the DTS Tomcat
Configure the DTS Tomcat to use standard internet ports
Configure the DTS Tomcat’s Host elements
Configure CM1 to publish to DTS database
Create FTP user and setup CM1 publishing server definition
Open required ports
Operate the DTS Tomcat
Test and verify configuration before switching DNS
(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. Configure the DTS Tomcat to use standard internet ports:

By default, the DTS Tomcat installs using the custom HTTP and HTTPS ports of 9980 and 8443 (9970 and 9443 for Staging), respectively. This works well to avoid port conflicts if you are using the DTS Tomcat to test local publishing, or as a backline web server in a dual server environment.

To deploy the DTS Tomcat as your standalone web server, however, you will want to configure it to use the standard HTTP and HTTPS ports 80 and 443.

To do this, you will need to edit two elements in the Tomcat’s server.xml file, which is located in the <dts_root>\Deployment\Server\conf directory. Open the file in a plain text editor, such as Notepad++ for Windows, or vi for Linux.

2.1. Change HTTP connection port:

Look for this line, which controls the server’s primary HTTP connection port:

(The port numbers will be different for a Staging DTS).

Change the port value to 80, and the redirectPort value to 443. The edited line should look like this:

2.2. Change primary HTTPS connection port:

Next, find this line, which manages the server’s primary HTTPS connection port:

Change the port value to “443”, like so:

Save the file. Your DTS Tomcat is now configured to run using the standard HTTP and HTTPS ports.

3. Configure the DTS Tomcat’s Host elements:

The Tomcat Host elements manage how hostnames bound to the web server’s IP address (www.percusison.com, for example) are directed by Tomcat to specific root folders on your web server’s file system. If no new Host element is configured, by default any connection made to your web server over the Tomcat’s connector ports (80 and 443, as configured in the previous step) will resolve to the <dts_root>\Deployment\Server\webapps\ROOT folder, which will display the default Tomcat welcome page.

To configure new virtual hosts that will point visitors to your site to the web content published by CM1, open up Tomcat’s server.xml file in a plain-text editor, which is located in the <dts_root>\Deployment\Server\conf directory.

3.1 Adding a new Host element:

Near the bottom of your server.xml file you will find a block of text that looks like this:

</Host>

This is the default DTS Host element. It very important that you leave this Host element untouched, as it points Tomcat to the WAR files needed to deployed Delivery Tier Services (DTS).

To add a new Host element, create a new line following the above closing Host tag and input a new Host element (right before the following Valve element). In this new Host element you will need to include the name and the appBase properties.

A typical new virtual host would look like this:

The name property is pretty self explanatory in this example. The value here should be the fully qualified domain name for your website (e.g. www.percussion.com).

The appBase property should point to where your site’s {sitename}apps folder will be created on your filesystem. In the example above, the c:/path/to/ portion is entirely up to you. Off of that directory, CM1 will create an {sitename}apps folder which will simply combine your site’s name in CM1 followed by “apps”.

With the above configuration, anyone who accesses your server over www.percussion.com will be directed to any web pages located in the C:\web_root\percussion.comapps\ROOT directory on your web server.

3.2 (Optional) Using Alias for non-WWW domain:

With the configuration above, only the full www.percussion.com domain name will resolve to the expected DTS Tomcat site. The non-WWW (or “naked”) domain, percussion.com, will send users to the default Tomcat landing page, as Tomcat will be falling back on the original “localhost” virtual host for any undefined host name that resolves to your web server.

Depending on your hosting provider, you may have an option to easily configure a DNS redirect which would send percussion.com to www.percussion.com. This is a common approach and would require no additional configuration.

Alternately, you can include an Alias element within your Host element, which would intercept connections coming in over percussion.com and direct them to this particular virtual host. That would look like this:

<Alias>percussion.com</Alias>

</Host>

With this approach, in essence you are simply adding an additional value to your main name attribute.

3.3 (Recommended) Configuring additional Host element for QA testing:

It is a good practice to setup an additional Host element for QA testing before going live with your CM1 site. This new virtual host would essentially be a duplicate of the primary virtual host that you’ve already created, with the difference being you would configure this one’s name attribute to use either the server’s IP address or a temporary sub domain (such as cm1-web.percussion.com) that you have assigned 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 will display and behave on your server before switching your DNS records to point your primary domain name to this new server.

Note: This will not be an option if, as touched on in this document’s “Prerequisites and considerations” section, you have your existing web server running on this same machine using HTTP and HTTPS ports 80 and 443. An alternative would be to temporarily revert your DTS Tomcat back to the default ports it had been using before following the steps in section 2 (“Configure the DTS Tomcat to use standard internet ports”), and access the DTS Tomcat over those non-standard ports while your current server continues to operate over the primary HTTP ports.

4. Configure CM1 to publish to DTS database:

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 match 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. This URL will only be used by the CM1 application. This typically would be set to your site’s fully qualified domain name too, but it can also be set to a private IP address or hostname that 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, for example https://www.percussion.com.

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://www.percussion.com</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 custom DTS ports, 9980 and 8443 (9970 and 9443 for Staging), must be removed from the URLs because we have configured the DTS Tomcat to operate using the standard HTTP and HTTPS ports of 80 and 443.

For any of the changes to 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 3.1 (“Adding a new Host element”), we configured the DTS Tomcat to use the appBase c:/path/to/percussion.comapps. In this case, your CM1 FTP user should be setup using C:\path\to\ as the home or root directory. The {sitename}apps subfolder – along with all other subfolders – will be created during the CM1 publishing operation.

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:

How to 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 (using C:\path\to\ as the home or root), and can simply use a single forward slash (“/”) in this field.
Ensure that you leave “Use Percussion web server setup” option selected. This will ensure that both a {sitename}apps and ROOT folder will be created off of the root FTP folder location – which is typically required for Tomcat web servers – along with a WEB-INF folder containing additional Tomcat configuration resources.
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.

***6.1.* *Open ports through firewall:***

The CM1 application server will need to make outbound connections over port 443 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.2.* *Verify ports:***

After opening the required ports through your firewall, it’s 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} 443

Where {admin-connection-url} matches the hostname in the admin-connection-url element identified in the above section (e.g. www.percussion.com). 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:

sudo nohup ./TomcatStartup.sh &

To stop the DTS, run:

sudo ./TomcatStartup.sh

Note that you must use “sudo” (or be logged in as the root user) to run the DTS Tomcat when it is setup as a frontline web server, because on most Linux machines, only the root user can open ports below 1024.

Additionally, “nohup” and “&” can be used (as in the example above) to ensure that the process is not tied to your terminal window.

8. Test and verify configuration before switching DNS records:

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

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 populate in the folder {ftp_root}\{sitename}apps\ROOT\ (following the example in section 3.1, this would be C:\path\to\percussion.comapps\ROOT). In this ROOT folder, you should find at least an “index” file and both a web_resources and a WEB-INF folder.

With your site’s content in place on your web server’s filesystem, you can start up your DTS Tomcat server as outlined in section 7 above. If you followed the recommended step 3.3 (“Configuring third Host element for QA testing”), you should now be able to access and review your site using the server’s IP address or whatever subdomain (e.g. cm1-web.percussion.com) you used in the additional Host element.

Once you’ve ensured that everything appears and is functioning as expected, you are now free to make the DNS switch pointing your primary domain name over to this new web server.

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