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:
Procedure
- Prepare your Apache Tomcat application server:
- 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.
- Increase the maximum file size and request size:
For Tomcat 7:
- Open the web.xml file of the Tomcat manager application, for example
<Tomcat_install_dir>/webapps/manager/WEB-INF/web.xml.
- 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>
- 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>
- Save and close the web.xml file.
For Tomcat 8: - Stop your Apache Tomcat application server.
- Delete the dgaas directory and dgaas.war from
<Tomcat_install_dir>\webapps directory if they already
exist.
- Copy the dgaas.war file to the
<Tomcat_install_dir>\webapps directory.
- Optional:
If
you want to run the Document Builder application
with DB2, you must
complete these extra configuration steps: - Copy the JDBC 4.0 Driver db2jcc4.jar file from the
<DB2_install_dir>/java directory to the
<Tomcat_install_dir>/lib directory.
- Open the Apache Tomcat startup script file:
<Tomcat_install_dir>\bin\catalina.bat
<Tomcat_install_dir>/bin/catalina.sh
And add the following line of
code:set "VCAP_SERVICES={'sqldb':[{}]}"
- 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.
- 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>
- Start the Apache Tomcat application server:

- 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

- 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
- 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.
- Open the Apache Tomcat Manager in a browser at
http://server:port/manager/html
Example:
http://localhost:8080/manager/htmlTip: 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"/>
- Deploy both the rpeng.war and dgaas.war applications
on Apache Tomcat.
- 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:
- Context Path: Enter /rpeng as the name for the
Document Builder.
This entry is a part of the URL used for configuring the client.
- XML Configuration file URL: Not required.
- 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:
- Select WAR to upload: The path to the rpeng.war
file. Example: RPE_HOME\document-builder\rpeng.war
- 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:
- Context Path: Enter /dgaas as the name for the
Document Builder.
This entry is a part of the URL used for configuring the client.
- XML Configuration file URL: Not required.
- 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:
- 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:
- 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.
- In the user toolbar of the Document Builder, select
Admininster. This Administer menu option is available
to users with rpe_admin role.
- Select Runtime Variables.
- 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.