Note: This document is a supplement to the SCN Document Improving the User Experience in SAP BI Platform 4.0 with Apache and WDeploy.  There are functional and configuration changes needed to deploy the solution successfully using the latest versions of SAP BusinessObjects BI Platform and Apache HTTPD.  The core concepts covered in the previous document remain unchanged unless otherwise mentioned.

Table of Contents

• Downloading Apache 2.4 for Windows and supporting pre-requisites
• Installation of Apache 2.4 as a Windows service
• Running WDeploy in split mode
• Configuration of httpd.conf and httpd-bi41.conf
• Deploying both static content and fully formed war files on Tomcat for supportability

Downloading Apache 2.4 for Windows and supporting prerequisites

Since the release of the last document on this subject, generation of Windows binaries for Apache HTTPD has become a hot topic on the Apache users list.  For a period of time only source code was available (as is the case with Linux/Unix versions) and, as of the time of writing, only 32-bit Windows binaries were available.

Due to these uncertainties, it is recommended that Windows users download Apache 2.4 from Apache Lounge, a website dedicated to supporting the HTTPD server project (i.e. Apache).  Apache Lounge also provides supporting modules, such as mod_jk, and 64-bit binaries for comprehensive Windows support.  For Linux/Unix implementations, it is recommended that you follow the instructions outlined in the BI4 Linux Pattern Book to build the server, and then follow the concepts in this document for configuration.

On Windows, it is also necessary to install the Visual C++ 2010 SP1 Redistributable Package x64 as these components are used to build the Apache server.

The following steps outline the required downloads for Apache 2.4:

1. Download the Apache 2.4 64-bit package from http://www.apachelounge.com/download/win64/
   • At the time of writing, the latest version was 2.4.7
2. Download and Install the Visual C++ 2010 SP1 Redistributable Package x64 from http://www.microsoft.com/download/en/details.aspx?id=13523
3. Download the mod_jk connector binary from http://www.apachelounge.com/download/win64/
   • At the time of writing, the latest version was 1.2.37
   • Extract the included mod_jk.so and place it in E:\Apache24\modules (or whichever directory you extract Apache to) after you have completed the next section

Once these 3 items have been downloaded, and the VC++ dependency installed, you are ready to proceed to the next step.

Installation of Apache 2.4 as a Windows Service

The archive for Apache 2.4 contains the zipped directory structure of the web server and does not have a standard Windows installer.  As such, it is necessary to extract the archive to a location of your choice, modify the configuration files to match your installation path, and install a Windows service.  The structure of the archive is as follows:

By default, the zipped configuration expects to find the installation in C:\Apache24.  If you're able to extract it there you won't need to make any path based changes to the config files.  In this document, however, I will extract the install to E:\Apache24 to demonstrate what you will need to do to install Apache in a non-standard path or drive.

After extracting the installation to E:\Apache24 the next step is to modify the httpd.conf file to reflect the new path.  For a production environment it is likely you will need to modify permissions, configure SSL, and add modules for maintenance and support.  Please refer to the Apache HTTPD 2.4 documentation for a comprehensive list of configuration options.  Open the file E:\Apache24\conf\httpd.conf in a text editor such as Notepad and locate the following lines:

ServerRoot "c:/Apache24"
DocumentRoot "c:/Apache24/htdocs"<Directory "c:/Apache24/htdocs">
ScriptAlias /cgi-bin/ "c:/Apache24/cgi-bin/"<Directory "c:/Apache24/cgi-bin">

Modify the paths to match the location of your installation, in this case E:/Apache24.  Note that the file uses a Linux style path structure containing forward slashes instead of back slashes.  BI 4.1 does not require use of CGI scripting so it may be disabled completely if desired.  Save the file and exit.

The next step is to install Apache as a Windows service.  This is done from the command line with a special directive to the httpd.exe executable.  The following steps outline the process:

1. Launch a Windows command prompt by running Start > Run > cmd
2. Navigate to the Apache bin directory, in this case E:\Apache24\bin using a command like cd\Apache24\bin (you may need to change drives first)
3. Install a Windows service that shows up in the Central Configuration Manager by executing the command:
   
   httpd -k install -n BOEXI40Apache
   
   
   • Note that the CCM is configured to render any services labeled with a prefix of BOEXI40.  By doing this we allow it to appear in the CCM for ease of management.
     
     
4. Change the display name of the service to include the version of Apache:
   
   sc config BOEXI40Apache -displayname= "Apache HTTPD 2.4.7"
   
   The command should return successfully as below:
   
   
   
   
5. Confirm that the CCM now shows the Apache HTTPD 2.4.7 service and that it can be started successfully:
   
   

Note that if you have the World Wide Publishing Service (IIS) on the server, it is required that you stop/disable it or ensure it runs on a port other than 80.  You may test that Apache is running properly by accessing http://localhost.  If the server is up and running you should get a simple HTML page with the text, "It works!"

Running WDeploy in split mode

Now that Apache is installed and running, it is possible to split the static content and deploy it to your web server.  It is recommended that you stop your application server, specifically if you're running Tomcat, as there can be file locking problems during the deploy phase of WDeploy.  Furthermore, you should temporarily disable your virus scan software during the WDeploy phase, as there are thousands of files being written and an active virus scan can increase the time needed to complete the process by a large number of hours.  In my case, running WDeploy with the virus scan disabled took ~25 minutes, while running it with the virus scan enabled took ~6 hours.

First, it is necessary to configure the WDeploy files so that the tool knows where to find your Apache distribution.  Browse to the location C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\wdeploy\conf and open the file config.apache in a text editor such as Notepad.

Locate and update the following lines:

ws_dir=E:/Apache24
connector_type=tomcat7

Where ws_dir is the location of your Apache installation and connector_type is the application server in use.  If you are using the default BI 4.1 installation the value of connector_type will be tomcat7.  Save and exit the file.

Next step is to run the WDeploy tool with certain parameters instructing it to split static and dynamic content.  I'll cover a couple of scenarios here, primarily using a separate work directory of your choice to build the web applications, as well as the workaround for MOBIServer outlined in SAP Note 1900589.  We'll break the WDeploy process into two steps, the first being the predeploy action.  This action instructs the WDeploy tool to build the web applications from the source files provided with the installation, taking into account any custom properties files or branding that you have implemented.

Run the following commands to invoke the predeploy action:

1. Start > Run > cmd
2. Change to the WDeploy directory (in my case that is E:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\wdeploy)
3. wdeploy tomcat7 -Das_mode=split -Dws_type=apache -Dwork_dir=e:\temp predeployall
   • The parameters are as follows:
   • tomcat7 >> the target application server, in this case Tomcat 7
   • -Das_mode=split >> instructs WDeploy to create zip files containing static content such as JavaScript and Cascading Style Sheets as well as dynamic content packaged in war files.
   • -Dws_type=apache >> the target web server, in this case Apache.  This instructs WDeploy to read the config.apache file we configured earlier.
   • -Dwork_dir=e:\temp >> instructs WDeploy to write temporary files to the specified directory.  This can be especially helpful if your install drive is running low on space.  It is also helpful to find the predeployed files and make the adjustment noted in SAP Note 1900589.
   • predeployall >> WDeploy builds the application files but does not deploy them to Apache and Tomcat.  We need to make an adjustment prior to deploying them.
4. Upon completion of the predeploy action the work directory should look something like this:
   
   Note the zip files located in ${work_dir}\temp\tomcat7\resources.  We can see that the BOE static resources file contains ~1.8GB of static content!  In this example I also have Explorer installed, which as you can see from above is also supported for split deployment.

Now that the predeploy phase is complete, we will implement a workaround for the MOBIServer and deploy the previously built files to our web and application server pair.  The reason for this step is that there are no static resource files associate with the MOBIServer ... everything is dynamic.  We can see in the output of the previous action:

However, in the deploy phase WDeploy will still look for a file called MOBIServer.zip and if it doesn't exist, the process will fail and throw an error.  Fortunately there is an easy workaround documented in SAP Note 1900589 and for the sake of propriety I will cover it here.

To implement the workaround, perform the following steps:

1. Navigate to the WDeploy static resource directory, in this case E:\temp\tomcat7\resources
2. Right-click somewhere on the empty canvas > New > Compressed (zipped) folder
   
   
   
   
   
   
3. Name the file MOBIServer (Windows should automatically handle the file extension so the full name should be MOBIServer.zip)
4. This will create an empty zip file that WDeploy can use to create a placeholder directory within Apache.

After this step is complete, we can run the deployonly action which will deploy our web applications without building them again.  From the command line, run the following commands:

cd E:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\wdeploy

wdeploy tomcat7 -Das_mode=split -Dws_type=apache -Dwork_dir=e:\temp deployonlyall

Once completed, the output should look something like this:

At this point, we want to confirm that the files were correctly deployed to Apache and Tomcat.  Start by opening the htdocs directory within Apache24 and look for the following folder structure:

Next, navigate to the Tomcat webapps directory (in my case, E:\Program Files (x86)\SAP BusinessObjects\tomcat\webapps) and verify the folder structure looks something like this:

Now we can perform the post-configuration steps necessary to ensure our split deployment is working as expected.

Configuration of httpd.conf and httpd-bi41.conf

It is time to configure the Apache web server to accelerate static content and provide the best overall BI user experience.  These topics are covered in the Configuration chapter on Page 17 of Improving the User Experience in SAP BI Platform 4.0 with Apache and WDeployso I will only cover the areas that are different here.  The document describes creation of a file called httpd-bi40.conf but since we are now using BI 4.1, we will call the resultant file httpd-bi41.conf.

Once you have loaded the appropriate modules and enabled the AJP connector in Tomcat's server.xml there are 2 changes from Apache 2.2 that must be implemented.  They deal with mod_deflate which handles HTTP compression, and mod_cache which provides a disk based caching mechanism for static content.

Update the httpd-bi41.conf file as follows:

#====================Configure mod_deflate==============
SetOutputFilter DEFLATE
#Highest 9 - Lowest 1
DeflateCompressionLevel 9
# Don't compress images
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png)$ no-gzip dont-vary
#Optional
#Logging
DeflateFilterNote ratio
LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
CustomLog logs/deflate_log.log deflate

The difference from Apache 2.2 is that we no longer compress by MIME type, but rather enable compression globally and disable based on specific file extensions.  Therefore, this section sets the output filter to DEFLATE which represents compressed content, and disables it for images which are already compressed.

The other change is a small one, but if you don't make it your Apache server won't start.  Apache has changed the naming syntax of mod_cache to be consistent in convention.  Therefore, mod_disk_cache has been renamed to mod_cache_disk.

Update httpd-bi41.conf as follows:

LoadModule cache_module modules/mod_cache.so
LoadModule cache_disk_module modules/mod_cache_disk.so

Then, update the mod_cache section as follows:

#====================Configure mod_cache==============<IfModule mod_cache.c>
#Address the Thundering Herd identified in Apache’s Caching Guide
CacheLock on
CacheLockPath E:/temp/mod_cache-lock
CacheLockMaxAge 5
#This parameter tells Apache to ignore unique session identifiers when caching
#static content.  SAP BI Platform 4.1 uses the strings jsessionid and bttoken to
#identify user sessions.
CacheIgnoreURLSessionIdentifiers jsessionid bttoken
#Don’t cache cookies as they are unique per user
CacheIgnoreHeaders Set-Cookie
#Enable mod_cache_disk instead of mod_cache_disk<IfModule mod_cache_disk.c>
CacheRoot e:/cacheroot
CacheEnable disk /
CacheDirLevels 2
CacheDirLength 1</IfModule></IfModule>

Make sure the paths are correct for your environment.  In mine, the cacheroot directory is at the root of the E drive.  Save and exit the httpd-bi41.conf file.

Next, navigate to E:\Apache24\conf and open the httpd.conf file in a text editor such as Notepad.  Navigate to the bottom of this file and add the text:

Include conf/extra/httpd-bi41.conf

Immediately preceding the entries added by WDeploy.  The resultant file should look something like this:

Save and exit the httpd.conf.  The environment is now ready to test, so restart Apache and Tomcat and ensure your BI servers are running and available.  If either Apache or Tomcat fail to start, check the syntax of your configuration files, and leverage the Troubleshooting section on Page 29 of Improving the User Experience in SAP BI Platform 4.0 with Apache and WDeploy.  You should now be able to access the BI Launch Pad logon page at http://localhost/BOE/BI.

Deploying both static content and fully formed war files on Tomcat for supportability

Although your environment will now be functional, the war files deployed to Tomcat no longer contain static content.  This means that you will no longer be able to interact with the BI applications on port 8080.  End users shouldn't be accessing Tomcat directly anyway, since that undermines the value proposition of the split deploy scenario, but it can be helpful for administrators in case of troubleshooting.  A couple of examples might be:

• A user receives a 404 error when accessing the BI Launch Pad through Apache.  There have been cases where SAP misses one or more JkMount commands from our predefined configuration files, and in order to troubleshoot, you may want to bypass Apache and see if the problem is resolved.  Once you confirm the file exists on Tomcat, it is simple to add an additional JkMount command and resolve the problem.
  
  
• Users experience occasional timeouts when performing certain actions (long-running interactive reports for example).  It can be helpful to run the report against Tomcat directly and determine if the timeout is related to Apache/mod_jk or not.

To enable this scenario, it is desirable to deploy fully formed war files to Tomcat, as well as static content to Apache.  At the cost of a few GB of disk space, you ensure that administrators can properly troubleshoot the environment.  We will run the WDeploy process again, but this time specify a simpler set of command line parameters.  You are welcome to use the command line version of WDeploy, or the GUI for ease of use.  Make sure you stop Tomcat before running WDeploy.  The command line syntax is as follows:

1. Start > Run > cmd
2. Change to the WDeploy directory (in my case that is E:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\wdeploy)
3. wdeploy tomcat7 deployall
4. Once the command completes the fully formed war files will have been deployed to your Tomcat server and the output should look something like this:
   
   
   

Now that WDeploy has completed, you would expect to restart Tomcat and be able to access BI Launch Pad again.  However, due to an architectural nuance introduced in BI 4.0 this is not the case.  Below I will demonstrate the change and explain how to address it.

In BI 4.0 SAP changed the BOE web applications to an Eclipse based framework that allows us to make certain changes without restarting the application server.  Part of this new framework introduced a date/time stamp component on the directory containing the web applications.  For Tomcat, this date/time stamp component has no effect on URL requests, and any value should still find its way to the BOE web application (this is handled internally by Tomcat).

With Apache, however, we create a physical folder structure containing the date/time stamp in the htdocs directory.  This means that when we ran the previous step, the timestamp on the folder changed within Tomcat, but remained the same in Apache, and now the two are out of synch.  We can see an example of this by using an HTTP proxy like Fiddler:

Note the 404 errors for static content, such as utils.js.  The date/time stamp that Tomcat is directing Apache to look for is:

1312181030

Which represents December 18, 2013 at 10:30 am.

You can also find this information in the access.log for Apache that is located in E:\Apache24\logs\access.log as below:

If I browse to E:\Apache24\htdocs\BOE\portal I see a folder called 1312161455 (or December 16, 2013 at 2:55 pm) as below:

Therefore, the solution is to rename this folder, and any other ones that use the same date/time stamp configuration, to match what Tomcat expects.  To do this:

1. Stop Apache from the CCM
2. Rename the folder in E:\Apache24\htdocs\BOE\portal to match the value returned by Fiddler or found in the Apache access.log
3. Make the same change to the folders in E:\Apache24\htdocs\BOE\OpenDocument and E:\Apache24\htdocs\BOE\CMC
   
   Since the BOE web application is the only one that uses this naming convention the remaining htdocs folders do not need to be modified.
   
   
4. The resultant folder structure should now look something like this:
   
   
   
   
5. Restart Apache

Now if we access the BI Launch Pad we can see that the static files are appropriately found within the Apache server:

The environment is now configured with BI Platform 4.1 SP2 and Apache 2.4.