Custom Deployment of Publishing Document Builder on IBM WebSphere Liberty

You can customize the deployment of Publishing Document Builder on IBM WebSphere® Liberty.

1. To start the WebSphere Liberty server server that is packaged with Publishing Document Builder, go to the command line and start the server from:
   • : Document_Builder_InstallDir\server\server.startup.bat

     For example, C:\Program Files\IBM\DocumentBuilder\server\server.startup.bat

   • : Document_Builder_InstallDir/server/server.startup

     For example, opt/IBM/DocumentBuilder/server/server.startup

   The Liberty server successfully starts when the console outputs the message: Server clm started.

   The following is an example of the console output when the Liberty server is first created and successfully started:

   Server clm created.
   630 File(s) copied
   Starting server clm.
   Server clm started.

   Remember: To later stop Liberty, go to the command line and stop the server from:

   • : Document_Builder_InstallDir\server\server.shutdown.bat

     For example, C:\Program Files\IBM\DocumentBuilder\server\server.shutdown.bat

   • : Document_Builder_InstallDir/server/server.shutdown

     For example, /opt/IBM/DocumentBuilder/server/server.shutdown

   The Liberty server successfully stops when the console outputs the message: Server clm stopped.

2. For Linux, set the TELELOGIC_LICENSE_FILE licensing variable.
   Create a server.env file that includes TELELOGIC_LICENSE_FILE=port@server. See Customizing the Liberty environment.
3. Create a database for the Publishing Document Builder with 16 K pages and UTF-8 code set.
   • For Db2 : For example, to create a database called pubdb with 16 K pages and the UTF-8 code set, use the following command:

     db2 CREATE DATABASE pubdb AUTOMATIC STORAGE Yes USING CODESET UTF-8
         TERRITORY US COLLATE USING SYSTEM PAGESIZE 16384;

     See the Db2 product documentation for information about creating a database.
   • For Oracle, see Creating database and table spaces section.
   • For Derby: Not applicable.
4. For Db2 , or Oracle set the VCAP_SERVICES variable(not required for Derby):
   • For Windows: Add the following text to the Document_Builder_InstallDir\server\liberty.server.bat file :

     set VCAP_SERVICES={"sqldb":[{}]}

   • For Linux: Add the following text to the Document_Builder_InstallDir\server\liberty.server file:

     export VCAP_SERVICES={"sqldb":[{}]}

5. Edit the server.xml file to configure the database connectivity for Liberty server.
   1. Define a shared library that points to the location of your JDBC driver (.jar) or compressed files (not required for Derby).
      For Db2 :

      <jdbcDriver id="db2-lib">
                 <library>
                     <fileset caseSensitive="false" dir="C:\Program Files\IBM\SQLLIB\java"/>  
                 </library> 
                </jdbcDriver>

      For Oracle:

      <jdbcDriver id="OracleLib">
                 <library>
                      <fileset caseSensitive="false" dir="/oracle_jdbc" includes="*.jar"/>  
                 </library> 
                </jdbcDriver>

   2. Define a data source that uses the JDBC driver for the rpeng and dgaas data sources with database connection details (not required for Derby).
      For Db2

      <dataSource id="rpeng" jdbcDriverRef="db2-lib" jndiName="jdbc/RPENG_DB">
                 <properties.db2.jcc databaseName="pubdb" portNumber="portNumber" password="password" serverName="ipaddress" user="db2admin"/>
                </dataSource> 
               <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
                 <properties.db2.jcc databaseName="pubdb" portNumber="portNumber" password="password" serverName="ipaddress" user="db2admin"/>
                </dataSource> 

      For Oracle:

       <dataSource id="rpeng_db" jdbcDriverRef="OracleLib" jndiName="jdbc/RPENG_DB">
             <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname:port/lib1" user="pub_user"/>
          </dataSource>
          <dataSource id="DGAAS_DB" jdbcDriverRef="OracleLib" jndiName="jdbc/DGAAS_DB">
             <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname:port/lib1" user="pub_user"/>
          </dataSource>

   See Configuring database connectivity in the WebSphere Liberty in the WebSphere Liberty server product documentation.
6. Verify your configuration settings against the server.xml example available towards the end of this topic in the Example section.
7. Set the heap size for the Java virtual machine. The maximum heap size should be incremented to not exceed 50 % of the overall physical memory. By default, the heap memory is set to 4 GB. If concurrent document-style report generation is set to a larger number, or if you are running large document-style report generation jobs, set a larger heap size. Heap memory can be updated in server.startup.bat file in Document_Builder_InstallDir/server.
   1. Update the following Java parameters to change the heap memory.

      set JAVA_OPTS=%JAVA_OPTS% -Xmx4G

      set JAVA_OPTS=%JAVA_OPTS% -Xms4G

      set JAVA_OPTS=%JAVA_OPTS% -Xmn1G

   2. Restart the server to enable changes.
   3. To verify the Status of the Document Generation Service, open https://hostname:port/dgaas/debug.
      
   4. To verify the database status, open https://hostname:port/dgaas/debug/db.
8. In a web browser, open the Publishing Document Builder application. The URL specified depends on an HTTPS or HTTP connection:
   • https://<hostname>:9444/rpeng/login.jsp
   • http://<hostname>:9081/rpeng/login.jsp
   Here <hostname> is the fully qualified domain name or localhost.
   Tip: Publishing Document Builder by default occupies 9444 for HTTPS and 9081 for HTTP. If you need to change the ports, back up your server.xml file and then edit the appropriate port numbers at Document_Builder_InstallDir\server\liberty\servers\clm\server.xml

   For example,

   • : C:\Program Files\IBM\DocumentBuilder\server\liberty\servers\clm\server.xml
   • : /opt/IBM/DocumentBuilder/server/liberty/servers/clm/server.xml
9. When you are prompted, provide your username and password to authenticate the Publishing Document Builder application and click Log in.
   • You can log in with any of the default users. The username and password of the default users are based on the user role:

     Username	Password
     pub_user	pub_user
     pub_designer	pub_designer
     pub_admin	pub_admin

   • Request an administrator to add new users to the basicUserRegistry.xml file and restart the server. See Configuring users for Publishing Document Builder on IBM WebSphere Liberty topic.
     Tip: The basicUserRegistry.xml file is at Document_Builder_InstallDir\server\liberty\servers\clm\conf\basicUserRegistry.xml

<httpSession invalidateOnUnauthorizedSessionRequestException="true"></httpSession>

<?xml version="1.0" encoding="UTF-8"?>
<server description="new server">
    <!-- Enable features -->
    <featureManager>
       <feature>jsp-2.2</feature>
       <feature>jndi-1.0</feature>
       <feature>jpa-2.0</feature>
       <feature>jdbc-4.0</feature>
       <feature>servlet-3.0</feature>
       <feature>appSecurity-2.0</feature>
    </featureManager>
    <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
    <httpEndpoint id="defaultHttpEndpoint" httpPort="9081" httpsPort="9444" host="localhost"/>
    <classloading useJarUrls="true"/>
    <!-- User creation-->
    <httpSession invalidateOnUnauthorizedSessionRequestException="true"/>

<classloading useJarUrls="true"/>

<webContainer deferServletLoad="false"/>

<include location="conf/basicUserRegistry.xml"/>

<include location="conf/application.xml"/>

<executor coreThreads="100"/>

<webAppSecurity ssoRequiresSSL="true" ssoUseDomainFromURL="true" ssoCookieName="rpeLtpaToken2"/>

<!--<webAppSecurity singleSignonEnabled="false" />-->


<applicationManager autoExpand="true"/>
    <!--Database Configuration -->
    <jdbcDriver id="db2-lib">
       <library>
          <fileset caseSensitive="false" dir="C:\Program Files\IBM\SQLLIB\java"/>
       </library>
    </jdbcDriver>
    <dataSource id="rpeng" jdbcDriverRef="db2-lib" jndiName="jdbc/RPENG_DB">
       <properties.db2.jcc databaseName="databasename" portNumber="portNumber" password="password" serverName="ipaddress" user="db2admin"/>
    </dataSource>
    <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
       <properties.db2.jcc databaseName="databasename" portNumber="portNumber" password="password" serverName="ipaddress" user="db2admin"/>
    </dataSource>
</server>

<?xml version="1.0" encoding="UTF-8"?>
<server description="new server">
    <!-- Enable features -->
    <featureManager>
       <feature>jsp-2.2</feature>
       <feature>jndi-1.0</feature>
       <feature>jpa-2.0</feature>
       <feature>jdbc-4.0</feature>
       <feature>servlet-3.0</feature>
       <feature>appSecurity-2.0</feature>
       <feature>ssl-1.0</feature>
    </featureManager>
    <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
    <httpEndpoint id="defaultHttpEndpoint" httpPort="9081" httpsPort="9444" host="localhost"/>
    <keystore id="defaultKeyStore" password="password"/>
    <classloading useJarUrls="true"/>
   <httpSession cookieSecure="true invalidateOnUnauthorizedSessionRequestException="true"></httpSession>
    <!-- User creation-->
    <httpSession invalidateOnUnauthorizedSessionRequestException="true"/>

<classloading useJarUrls="true"/>

<webContainer deferServletLoad="false"/>

<include location="conf/basicUserRegistry.xml"/>

<include location="conf/application.xml"/>

<executor coreThreads="100"/>

<webAppSecurity ssoRequiresSSL="true" ssoUseDomainFromURL="true" ssoCookieName="rpeLtpaToken2"/>

<!--<webAppSecurity singleSignonEnabled="false" />-->


<applicationManager autoExpand="true"/>
   
    <!--Database Configuration -->
    <jdbcDriver id="OracleLib">
       <library>
          <fileset caseSensitive="false" dir="/oracle_jdbc" includes="*.jar"/>
       </library>
    </jdbcDriver>
    <dataSource id="rpeng_db" jdbcDriverRef="OracleLib" jndiName="jdbc/RPENG_DB">
       <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname:port/lib1" user="pub_user"/>
    </dataSource>
    <dataSource id="DGAAS_DB" jdbcDriverRef="OracleLib" jndiName="jdbc/DGAAS_DB">
       <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname:port/lib1" user="pub_user"/>
    </dataSource>
</server>

<?xml version="1.0"?>

-<server>


-<application location="${server.config.dir}/apps/rpeng.war" name="rpeng" id="rpeng" type="war">

<classloader apiTypeVisibility="spec,ibm-api,api" commonLibraryRef="rcl"/>


-<application-bnd>


-<security-role name="pub_user">

<group name="JazzGuests"/>

</security-role>


-<security-role name="pub_report_designer">

<group name="JazzUsers"/>

</security-role>


-<security-role name="pub_admin">

<group name="JazzAdmins"/>

</security-role>

</application-bnd>

</application>


-<application location="${server.config.dir}/apps/dgaas.war" name="dgaas" id="dgaas" type="war">

<classloader apiTypeVisibility="spec,ibm-api,api" commonLibraryRef="rcl"/>


-<application-bnd>


-<security-role name="pub_user">

<group name="JazzGuests"/>

</security-role>


-<security-role name="pub_report_designer">

<group name="JazzUsers"/>

</security-role>


-<security-role name="pub_admin">

<group name="JazzAdmins"/>

</security-role>

</application-bnd>

</application>

</server>

<?xml version="1.0" encoding="UTF-8"?>

-<server>

<!--Licensed Materials - Property of IBM(c) Copyright IBM Corporation 2015. All Rights Reserved.Note to U.S. Government Users Restricted Rights:Use, duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp. -->



-<featureManager>

<feature>appSecurity-2.0</feature>

</featureManager>


-<basicRegistry realm="Jazz" id="Jazz">

<user password="pub_admin" name="pub_admin"/>

<user password="pub_designer" name="pub_designer"/>

<user password="pub_user" name="pub_user"/>


-<group name="JazzAdmins">

<member name="pub_admin"/>

</group>

<group name="JazzProjectAdmins"> </group>


-<group name="JazzGuests">

<member name="pub_user"/>

</group>


-<group name="JazzUsers">

<member ="pub_designer"/>

</group>

</basicRegistry>

</server>