Deploying Document Builder on Apache Tomcat

You can deploy the Document Builder web applications (rpeng.war and dgaas.war) on an Apache Tomcat server with Derby or DB2®. If you want to run the Document Builder application on an enterprise database, the optional step in this task provides you with the extra configuration settings for DB2 support.

Before you begin

You must install Apache Tomcat V7.0.x or V8.0.x and Rational® Publishing Engine with the RPE Document Builder feature before deploying Document Builder.
You must have access to the following web applications available in the RPE_HOME\document-builder directory:
  • rpeng.war
  • dgaas.war

Procedure

  1. Prepare your Apache Tomcat application server:
    1. On the Tomcat application server, set TELELOGIC_LICENSE_FILE system variable to port_number@hostname, for example, 19353@licserver1. For more details, see Verify the TELELOGIC_LICENSE_FILE environment variable topic.
    2. Increase the maximum file size and request size:

      For Tomcat 7:

      1. Open the web.xml file of the Tomcat manager application, for example <Tomcat_install_dir>/webapps/manager/WEB-INF/web.xml.
      2. Find the following section:
        <multipart-config>
        <!-- 50 MB max -->
        <max-file-size>52428800</max-file-size>
        <max-request-size>52428800</max-request-size>
        <file-size-threshold>0</file-size-threshold>
        </multipart-config>
      3. Edit this section to increase the capacity:
        <multipart-config>
        <!-- 70 MB max -->
        <max-file-size>73400320</max-file-size>
        <max-request-size>73400320</max-request-size>
        <file-size-threshold>0</file-size-threshold>
        </multipart-config>
      4. Save and close the web.xml file.
      For Tomcat 8:
      1. Stop your Apache Tomcat application server.
      2. Delete the dgaas directory and dgaas.war from <Tomcat_install_dir>\webapps directory if they already exist.
      3. Copy the dgaas.war file to the <Tomcat_install_dir>\webapps directory.
  2. Optional: This is a DB2 icon. If you want to run the Document Builder application with DB2, you must complete these extra configuration steps:
    1. Copy the JDBC 4.0 Driver db2jcc4.jar file from the <DB2_install_dir>/java directory to the <Tomcat_install_dir>/lib directory.
    2. Open the Apache Tomcat startup script file:
      • This is a Windows operating system icon. <Tomcat_install_dir>\bin\catalina.bat
      • This is a Linux operating system icon. <Tomcat_install_dir>/bin/catalina.sh
      And add the following line of code:
      set "VCAP_SERVICES={'sqldb':[{}]}"
    3. Prepare an XML statement that defines the data source in the <Tomcat_install_dir>/conf/server.xml file:
      <Resource auth="Container"
                  driverClassName="com.ibm.db2.jcc.DB2Driver"
                  name="jdbc/RPENG_DB"
                  username="db2admin"
                  password="myDBpassword"
                  type="javax.sql.DataSource"
                  url="jdbc:db2://<server>:50000/rpedb1"/>
      <Resource auth="Container"
                  driverClassName="com.ibm.db2.jcc.DB2Driver"
                  name="jdbc/DGAAS_DB"
                  username="db2admin"
                  password="myDBpassword"
                  type="javax.sql.DataSource"
                  url="jdbc:db2://<server>:50000/rpedb1"/>
      Where the db2admin value after the usename attribute is the name of the system user with CONNECT access to the rpedb1 database, and myDBpassword after password is this user's password. If you have defined either a different user name, or a different password, or both, replace db2admin and myDBpassword accordingly. In addition, replace <server> with the address to your database server location.
      Tip: DB2 has a user name and password length limit of 8 characters for Linux operating systems, and 30 characters for Windows operating systems.
    4. Add the declaration for your resource in the <Tomcat_install_dir>/conf/context.xml file:
      <Context>
        ...
         <ResourceLink name="jdbc/RPENG_DB" global="jdbc/RPEBG_DB" type="javax.sql.DataSource"/>
         <ResourceLink name="jdbc/DGAAS_DB" global="jdbc/DGAAS_DB" type="javax.sql.DataSource"/>
      </Context>
  3. Start the Apache Tomcat application server:
    This is a Windows operating system icon.
    If you are running Apache Tomcat as a Windows service, to start the server, from the <Tomcat_install_dir>/bin directory, run this command (for Apache Tomcat V7.0.x, substitute with Tomcat7.exe):
    Tomcat8.exe start
    To stop the server, from the <Tomcat_install_dir>/bin directory, run this command (for Apache Tomcat V7.0.x, substitute with Tomcat7.exe):
    Tomcat8.exe stop
    If you are not running Apache Tomcat as a Windows service, to start the server, from the <Tomcat_install_dir>/bin directory, run this command:
    startup.bat
    Tip: A separate Apache Tomcat console window opens. Do not close this window or the server will stop working. You need to wait a moment for the Tomcat server to start. After the server is started, the start-up time in milliseconds is displayed in the Tomcat window. For example, Server startup in 25731 ms.
    To stop the server, from the <Tomcat_install_dir>/bin directory, run this command:
    shutdown.bat
    This is a Linux operating system icon.
    To start the server, from the <Tomcat_install_dir>/bin, run this command:
    startup.sh
    To stop the server, from the <Tomcat_install_dir>/bin directory, run this command:
    shutdown.sh
  4. Select one of the following options to deploy Document Builder:
    • If you want to deploy Document Builder using a graphical user interface, continue to the next step for details on deploying using the Apache Tomcat Manager interface.
    • If you want to deploy Document Builder using the file system, copy the rpeng.war and dgaas.war files from RPE_HOME\document-builder directory to the Tomcat webapps directory, for example, <Tomcat_install_dir>\webapps. And then continue to the Results and What to do next section of this topic.
  5. Open the Apache Tomcat Manager in a browser at http://server:port/manager/html
    Example: http://localhost:8080/manager/html
    Tip: A window opens asking for a user name and password to authenticate the Tomcat Manager Application. You must add a manager-gui role to the <Tomcat_install_dir>/conf/tomcat-user.xml file, where <Tomcat_install_dir> is the installation directory of the Apache Tomcat. The following example adds a manager-gui role with my_username as the user name and my_password for the password:
    <user username="my_username" password="my_password" roles="manager-gui"/>
  6. Deploy both the rpeng.war and dgaas.war applications on Apache Tomcat.
    1. In the Deploy section, enter the details for the rpeng.war file and then click Deploy:
      • If the WAR file is on a different server than Apache Tomcat, enter the following information in the Deploy directory or WAR file located on server section:
        1. Context Path: Enter /rpeng as the name for the Document Builder. This entry is a part of the URL used for configuring the client.
        2. XML Configuration file URL: Not required.
        3. WAR or Directory URL: The path to the rpeng.war file. Example: RPE_HOME\document-builder\rpeng.war
      • If the .war file is on the same server as Apache Tomcat, enter the following information in the WAR file to deploy section:
        1. Select WAR to upload: The path to the rpeng.war file. Example: RPE_HOME\document-builder\rpeng.war
    2. In the Deploy section, enter the details for the dgaas.war file and then click Deploy:
      • If the .war file is on a different server than Apache Tomcat, enter the following information in the Deploy directory or WAR file located on server section:
        1. Context Path: Enter /dgaas as the name for the Document Builder. This entry is a part of the URL used for configuring the client.
        2. XML Configuration file URL: Not required.
        3. WAR or Directory URL: The path to the dgaas.war file. Example: RPE_HOME\document-builder\dgaas.war
      • If the .war file is on the same server as Apache Tomcat, enter the following information in the WAR file to deploy section:
        1. Select WAR to upload: The path to dgaas.war. Example: RPE_HOME\document-builder\dgaas.war

Results

You can confirm that Document Builder is deployed by opening the introductory page in a browser at http://server:port/rpeng/
Important:

By default, the rpeng.war application looks for the dgaas.war application on the same server, under the /dgaas context path. If you deploy the dgaas.war application on a different server or a different context path, you must configure the DGAAS_URL runtime environment variable in the rpeng.war application.

To configure the DGAAS_URL runtime environment variable:
  1. You must log on to Document Builder, http://server:port/rpeng/, with a user that has administrator (rpe_admin) access. For details on how to configure a user with rpe_admin user role, see Configuring users for the Document Builder on Apache Tomcat topic.
  2. In the user toolbar of the Document Builder, select Admininster. This Administer menu option is available to users with rpe_admin role.
  3. Select Runtime Variables.
  4. Set the value of the DGAAS_URL runtime environment variable to a URL, such as http://server:port/dgaas.

What to do next

Optionally, you can deploy and run the Newskeeper sample application that uses document generation service technology for generating documents, and provides a storage interface for document generation service assets and documents. For more details, see Running the Newskeeper sample.

Configure the Rational Publishing Engine Document Builder listed on the http://server:port/rpeng/ page. See Document Builder URLs for an explanation of how each URL is used and tasks for configuring each of the features.

Feedback