DOCUMENTATION
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5 Rooted in Open Source CMS, Jahia’s Digital Industrialization paradigm is about streamlining Enterprise digital projects across channels to truly control time-to-market and TCO, project after project.
Jahia Solutions Group SA 9 route des Jeunes, CH-1227 Les acacias Geneva, Switzerland http://www.jahia.com
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
Summary 1
2
Overview ................................................................................................................................... 5 1.1
What’s in this documentation? ............................................................................................. 5
1.2
Notes.................................................................................................................................... 5
Prerequisites ............................................................................................................................. 7 2.1
WebSphere .......................................................................................................................... 7
2.2
Java ..................................................................................................................................... 7
2.3
Minimal system requirements .............................................................................................. 7
2.3.1 Operating system ........................................................................................................... 7 2.3.2 Memory .......................................................................................................................... 8 2.3.3 Disk ................................................................................................................................ 8 3
Digital Factory Installation ......................................................................................................... 9 3.1
Preparation .......................................................................................................................... 9
3.2
Running the installer ............................................................................................................ 9
3.2.1 GUI mode ....................................................................................................................... 9 3.2.2 Console mode ................................................................................................................ 9
4
3.3
Main installation steps ........................................................................................................ 10
3.4
Installation artifacts ............................................................................................................ 14
Server Configuration................................................................................................................ 16 4.1
Prerequisites ...................................................................................................................... 16
4.2
Configuration using wsadmin script.................................................................................... 16
4.3
Configuration using UI........................................................................................................ 17
© 2002 – 2014 Jahia Solutions Group SA
Page 2 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4.3.1 JVM options ................................................................................................................. 18 4.3.2 Web container .............................................................................................................. 19 4.3.3 Security – Programmatic session cookie configuration ................................................ 20 4.3.4 JDBC............................................................................................................................ 21 4.3.5 Shared libraries ............................................................................................................ 30 5
6
Deploying Digital Factory......................................................................................................... 35 5.1
Prerequisites ...................................................................................................................... 35
5.2
Deployment using wsadmin script ...................................................................................... 35
5.3
Deployment using UI .......................................................................................................... 37
Clustered Deployment ............................................................................................................. 55 6.1
Running the installer .......................................................................................................... 55
6.2
Processing node ................................................................................................................ 57
6.2.1 Server configuration ..................................................................................................... 57 6.2.2 Deploying Digital Factory ............................................................................................. 58 6.3
Non-processing node ......................................................................................................... 59
6.3.1 Preparation .................................................................................................................. 59 6.3.2 Server configuration ..................................................................................................... 61 6.3.3 Deploying Digital Factory ............................................................................................. 61 6.3.4 Verification ................................................................................................................... 61 6.4 7
Further non-processing nodes ........................................................................................... 62
Updating Digital Factory Using Fix Applier .............................................................................. 63 7.1
Prerequisites ...................................................................................................................... 63
© 2002 – 2014 Jahia Solutions Group SA
Page 3 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
7.2
Standalone Digital Factory installation ............................................................................... 63
7.3
Clustered Digital Factory installation .................................................................................. 65
7.3.1 Uninstall Digital Factory ............................................................................................... 65 7.3.2 Processing node .......................................................................................................... 66 7.3.3 Non-processing node ................................................................................................... 67 8
9
Portlet Deployment .................................................................................................................. 68 8.1
Prerequisites ...................................................................................................................... 68
8.2
Preparing a portlet Web application ................................................................................... 68
8.3
Deployment steps .............................................................................................................. 70
Frequently Asked Questions (FAQ) ......................................................................................... 87 9.1
Debugging in WebSphere .................................................................................................. 87
9.2
Mail setup with Gmail ......................................................................................................... 88
9.3
Copying repository indexes to other cluster nodes ............................................................ 89
© 2002 – 2014 Jahia Solutions Group SA
Page 4 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
1 Overview 1.1 What’s in this documentation? This document is intended to give an overview of the various aspects of advanced installation, configuration and the fine-tuning of Digital Factory v7.0 - Enterprise Distribution on IBM WebSphere Application Server. It is intended for system administrators and advanced users. This guide is structured in the following way: Chapter 2: Prerequisites and system requirements Chapter 3: Installation of Digital Factory using the installer Chapter 4: Configuration of the WebSphere server instance Chapter 5: Deployment of the Digital Factory into configured WebSphere server instance Chapter 6: Update process using Fix Applier Chapter 7: Portlet deployment guide Chapter 8: FAQ Should you have questions, please do not hesitate to contact us as mentioned on our Website (http://www.jahia.com).
1.2 Notes For the sake of simplicity, we will use “WebSphere” as a reference to “IBM WebSphere Application Server” product throughout this document.
© 2002 – 2014 Jahia Solutions Group SA
Page 5 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
All trademarks or registered trademarks, mentioned in this document, are the property of their respective owners.
© 2002 – 2014 Jahia Solutions Group SA
Page 6 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
2 Prerequisites 2.1 WebSphere The installation procedure, described in this guide, was tested on a 64-bit version of the IBM WebSphere Application Server version 8.5.5.2 Full Profile. As this platform evolves over time, it is possible that the installation may vary in points depending on the changes introduced in the platform. Make sure to read the release notes of any update packs that are installed on the server to adjust your deployment procedure accordingly.
2.2 Java IBM Java 1.7.x (non-IBM JDKs are not tested).
2.3 Minimal system requirements 2.3.1 Operating system A supported 64-bit operating system is required, such as RedHat Enterprise Linux 6 (see release notes for support of more recent versions), Windows 7. CentOS 6 is known to work but is not officially supported. Ubuntu/Debian or other Linux distributions are not recommended and not officially supported. In general it is highly recommended to stick as much as possible to the platforms, recommended by IBM. Please refer to the “Supported Stack” section with the system requirements for properly running Digital Factory v7.0 - Enterprise Distribution: http://www.jahia.com/customer-extranet/digitalfactory-jahia-7-0/supported-stack
© 2002 – 2014 Jahia Solutions Group SA
Page 7 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
2.3.2 Memory RAM: 4GB (minimum), 8GB (recommended).
2.3.3 Disk At least 20GB hard disk space (including WebSphere install)
© 2002 – 2014 Jahia Solutions Group SA
Page 8 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
3 Digital Factory Installation This chapter contains the main steps, required to install Digital Factory on your server. Please, follow all the steps in the following sections to complete the installation and after than continue with the next chapters: “4 Server Configuration” and “5 Deploying Digital Factory”. For a clustered Digital Factory deployment, please, refer to the chapter “6 Clustered Deployment”.
3.1 Preparation Download the latest stable Digital Factory 7.0 - Enterprise Distribution installer from http://www.jahia.com by choosing the right downloadable package for your operating system.
3.2 Running the installer 3.2.1 GUI mode You could run the graphical installer on any platform. On Windows it is enough to double-click the downloaded executable. On Linux servers with graphical environment, you can start the installation wizard by running:
java -jar
3.2.2 Console mode On a Linux server, where you have no graphical environment, or on a remote server, which is accessed via SSH, you can start the installation in the Console Mode:
java -jar -console
© 2002 – 2014 Jahia Solutions Group SA
Page 9 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
In case you would require running the wizard in Console Mode on Windows, you will need to open your command prompt with administrator privileges (see “Start a Command Prompt as an Administrator” http://technet.microsoft.com/en-us/library/cc947813%28v=ws.10%29.aspx).
3.3 Main installation steps Follow the installation wizard by specifying the installation path (please, avoid paths with spaces):
Choose “Custom install (advanced)” mode on the step 4 “Installation type”:
© 2002 – 2014 Jahia Solutions Group SA
Page 10 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
On step 5 “Select Installation Packages”, please, uncheck the option for bundled Apache Tomcat server:
© 2002 – 2014 Jahia Solutions Group SA
Page 11 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
And on the next step you will be able to select your target application server type (IBM WebSphere 8.5.5):
© 2002 – 2014 Jahia Solutions Group SA
Page 12 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
On the step 20 “Runtime data and configuration” you will have to choose the target folders where the node-specific Digital Configuration can reside and where the runtime data is located (deployed modules, JCR repository data and indexes, etc.):
© 2002 – 2014 Jahia Solutions Group SA
Page 13 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
3.4 Installation artifacts After performing above-mentioned steps, installer will produce the following artifacts in the /digital-factory folder (we reference here the selected installation folder ):
digital-factory/ |-- config/ |-- data/ | |-- db/ | |-- dbdata/ | |-- modules/ | |-- patches/ | |-- prepackagedSites/ | |-- repository/ | `-- scripts/ |-- jdbc-driver/ |-- shared-libraries/ |-- digitalfactory.ear |-- wsadmin-configure.py `-- wsadmin-deploy.py Here is a brief overview of the important folders:
config/: a folder where node-specific Digital Factory configuration is placed; it also contains the license.xml file with the current license.
data/: folder for runtime data, like deployed modules, JCR repository data and indexes, etc. This folder Digital Factory will write data into during its run.
jdbc-driver/: contains the JAR file (or files) with the JDBC driver for the DBMS, selected during installation.
shared-libraries/: folder with so called shared libraries - portlet container JARs, required by Web aplications, hosting portlets to be run in Digital Factory portlet container.
digitalfactory.ear: ready for deployment Digital Factory EAR file with the Web application.
© 2002 – 2014 Jahia Solutions Group SA
Page 14 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
wsadmin-configure.py: an automatically generated Jython script file for wsadmin tool that can be used to configure your WebSphere instance for Digital Factory, including all required settings, JDBC datasource configuration, shared libraries etc.
wsadmin-deploy.py: an automatically generated wsadmin-Jython script file for deploying Digital Factory into the configured WebSphere instance and starting it.
Please, backup the installed artifacts, especially the digitalfactory.ear, as it will be needed to perform Digital Factory updates when applying hotfixes and service packs.
© 2002 – 2014 Jahia Solutions Group SA
Page 15 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4 Server Configuration 4.1 Prerequisites We assume here that you have existing application server profile or have created a new one. Further we will reference the server profile directory as . We require the installation and configure of IBM’s Java 7 for that profile.
If you are deploying Digital Factory using ROOT (“/”) Web context path, please, ensure that the “Default application” of WebSphere is not installed (or uninstall it afterwards) to prevent conflicts with Digital Factory Web application. The server configuration can be done using either the generated wsadmin script or manually via the WebSphere Integrated Solutions Console (Web UI). The next sections cover both approaches in details.
4.2 Configuration using wsadmin script The Digital Factory installer automatically generates a Jython script – wsadmin-configure.py (see section “3.4 Installation artifacts”), which could be used to configure the server. It includes commands to:
Configure JVM options: initial and maximum heap size, permanent generation space size, temporary folder, verbose garbage collection etc.
Adjust the “Programmatic session cookie configuration”
Deploy Digital Factory portlet container JARs and node-specific configuration as shared libraries
© 2002 – 2014 Jahia Solutions Group SA
Page 16 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
Configure JDBC provider, datasource and connection pool
Before executing the script you could edit it and adjust, for example, the JVM memory settings or DB connection pool properties with regard to your platform requirements. The script tries to detect the node, cell and server IDs. But if you have multiple, you could edit the script and specify the IDs explicitly.
Ensuring that your server instance is currently running, execute the following command: Linux:
/bin/wsadmin.sh -lang jython -user password -f /digital-factory/wsadminconfigure.py Windows:
\bin\wsadmin.bat -lang jython -user password -f \digital-factory\wsadminconfigure.py The script forces the WebSphere server restart. Please, wait till the server is up again and continue with the steps in “5 Deploying Digital Factory” chapter.
4.3 Configuration using UI This section describes an alternative way of configuring your WebSphere instance using the Webbased UI (“WebSphere Integrated Solutions Console”), which in the default installation is accessible via http://localhost:9060/ibm/console. When performing changes to the configuration you will have to use “Save” action to save the changes directly to the master configuration.
© 2002 – 2014 Jahia Solutions Group SA
Page 17 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4.3.1 JVM options 1) Navigate to Servers -> Server types -> WebSphere application servers -> -> Java and Process Management -> Process definition -> Java Virtual Machine. 2) Specify at least 3 GB for the “Maximum heap size” and at least 384 MB for the permanent generation space. 3) Enable “Verbose garbage collection” and specify the following value for the “Generic
JVM arguments”:
-XX:MaxPermSize=384m -XX:+HeapDumpOnOutOfMemoryError agentlib:getClasses -Djava.net.preferIPv4Stack=true Djava.io.tmpdir=${WAS_TEMP_DIR}
© 2002 – 2014 Jahia Solutions Group SA
Page 18 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4) Click “OK” If you’re interested in debugging your WebSphere installation, you can see that in the above screenshot there is a checkbox for “Debug Mode”. For more information on how to use it, see the “9.1 Debugging in WebSphere” section later in this document.
4.3.2 Web container If you are planning to use portlets in Digital Factory, a special option needs to be set on the Web container. If not, you can skip to the next section. © 2002 – 2014 Jahia Solutions Group SA
Page 19 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
1) Open the Servers -> Server types -> WebSphere application servers -> -> Web Container Settings -> Web container -> Custom properties. 2) Click “New…” and provide com.ibm.ws.webcontainer.RedirectWithPathInfo as the name and true as a value.
3) Click “OK”.
4.3.3 Security – Programmatic session cookie configuration Digital Factory uses “/” for session cookie path (for interoperability with portlets), so you will have to adjust the session cookie security settings. 1) Go to Security -> Global security -> Programmatic session cookie configuration. 2) Here you need to delete the entry with the cookie name “JSESSIONID” and cookie path “/”.
© 2002 – 2014 Jahia Solutions Group SA
Page 20 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
3) Click on “OK”
4.3.4 JDBC You need to define a data source in your Application server for Digital Factory to be able to talk to the database server. This data source will be further mapped on the resources declared in your Digital Factory application.
4.3.4.1 JDBC provider 1) Open Resources -> JDBC -> JDBC providers 2) Select the server scope and click “New…” 3) Fill in the values like shown in the screenshot below:
© 2002 – 2014 Jahia Solutions Group SA
Page 21 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4) Click “Next” 5) On the next screen you will have to provide a path to the Oracle JDBC driver JARs (for Oracle there are two JAR files, for other DBMS it is a single one). Here you will have to enter the path to JARs files in the Digital factory installation directory (please, replace the placeholder with the absolute path), separated by (two lines):
/digital-factory/jdbc-driver/ojdbc6-12.1.0.1.jar /digital-factory/jdbc-driver/orai18n-12.1.0.1.jar
© 2002 – 2014 Jahia Solutions Group SA
Page 22 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
6) Click “Apply”, otherwise the values will be lost when you will navigate to next screen 7) Click “Next” 8) You will get the summary screen as below, where you will have to click “Finish”. Please, verify here the class path value.
© 2002 – 2014 Jahia Solutions Group SA
Page 23 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
9) Continue to the next section for creating the J2C authentication alias
4.3.4.2 J2C authentication data Here we will create the database user/password credentials as J2C authentication data. 1) Navigate to Security -> Global Security -> Java Authentication and Authorization
Service -> J2C authentication data 2) Uncheck the “Prefix new alias names with the node name of the cell (for
compatibility with earlier releases)” and click on Apply
3) Click on “New…” 4) In the creation screen provide the “jahiaJ2CAuthAlias” as an Alias (please, use this name, it will ease the configuration process); provide database user and password information and click on “OK”
© 2002 – 2014 Jahia Solutions Group SA
Page 24 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
5) Verify that the alias is properly created and the name is “jahiaJ2CAuthAlias”:
6) Continue to the next section for creating data source
4.3.4.3 Data source Here we will create the JDBC data source with the name “jdbc/jahia", which is required for Digital Factory. 1) Open Resources -> JDBC -> JDBC providers © 2002 – 2014 Jahia Solutions Group SA
Page 25 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
2) Click on the provider, we’ve created on the step “4.3.4.1 JDBC provider” 3) In the configuration screen for that provider, click on “Data sources” 4) Start creating a new data source by clicking on “New…” 5) On the first step enter “jdbc/jahia" as the JNDI name (the exact name is important for proper configuration)
6) Click “Next”
© 2002 – 2014 Jahia Solutions Group SA
Page 26 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
7) On the second step, provide the URL value for your database server and uncheck the “Use
this data source in container managed persistence (CMP)” option.
8) Click “Next”. 9) On the next screen, select in the “Component-managed authentication alias” select box the “jahiaJ2CAuthAlias” J2C authentication alias, we’ve created earlier.
10) Click “Next”
© 2002 – 2014 Jahia Solutions Group SA
Page 27 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
11) The step 4 is a summary screen where you can verify the values
12) Click “Finish” 13) After the data source is created click on it to open its properties 14) Click on “WebSphere Application Server data source properties”. Here uncheck the “Log missing transaction context” and check the “Non-transactional data source”:
© 2002 – 2014 Jahia Solutions Group SA
Page 28 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
15) Click on “OK” 16) Now click on “Connection pool properties”. Here you should adjust the connection pool properties to specify minimum and maximum number of connections in the pool, connection timeout, unused timeout and aged timeout. Update values:
© 2002 – 2014 Jahia Solutions Group SA
Page 29 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
17) and click on “OK” 18) The data source is now set up. Save the changes to master configuration and test the connection (“Test connection” button in the Data source overview page). 19) Proceed to the next section for deployment of shared libraries.
4.3.5 Shared libraries Digital Factory requires two groups of artefacts to be deployed as shared libraries:
The portlet container JARs are deployed using “Jahia Shared Libraries” name
© 2002 – 2014 Jahia Solutions Group SA
Page 30 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
Digital Factory configuration folder is deployed as a shared library using the name “ Jahia
Configuration” The names are used as IDs in various references. Please, verify that they are specified like stated above. The following sections describe the shared libraries deployment procedure in details.
4.3.5.1 Jahia Shared Libraries 1) Navigate to Environment -> Shared Libraries 2) Select your server as the scope and click on “New…” 3) On the next screen enter “Jahia Shared Libraries” as the name, the
“/ digital-factory/shared-libraries” as the Classpath (replacing the with the corresponding absolute path) and check the “Use an
isolated class loader for this shared library” option:
© 2002 – 2014 Jahia Solutions Group SA
Page 31 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4) Click on “OK” to save the changes 5) Continue to the next section
4.3.5.2 Jahia Configuration Is a similar way create the “Jahia Configuration” shared library entry: 1) Navigate to Environment -> Shared Libraries 2) Select your server as the scope and click on “New…”
© 2002 – 2014 Jahia Solutions Group SA
Page 32 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
3) On the next screen enter “Jahia Configuration” as the name, the “/
digital-factory/config” as the Classpath (replacing the with the corresponding absolute path) and check the “Use an isolated class loader for this
shared library” option:
4) Click on “OK” to save the changes 5) Finally you should have two shared library entries in the list:
© 2002 – 2014 Jahia Solutions Group SA
Page 33 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
The configuration of the server is completed. Please, save the changes to the master configuration and restart the server to ensure all the changes are effective. Proceed to the next chapter for the description of Digital Factory deployment steps.
© 2002 – 2014 Jahia Solutions Group SA
Page 34 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
5 Deploying Digital Factory 5.1 Prerequisites We assume here that the Digital Factory is successfully installed (see chapter “3 Digital Factory Installation”) and the server is properly configured (refer to chapter “4 Server Configuration”). Here we also reference the server profile directory as . The deployment can be done using either the generated wsadmin script or manually via the WebSphere Integrated Solutions Console (Web UI). The next sections cover both approaches in details.
5.2 Deployment using wsadmin script The Digital Factory installer automatically generates a Jython script – wsadmin-deploy.py (see section “3.4 Installation artifacts”), which could be used to deploy Digital Factory EAR to the server. We recommend you to increase the default timeout for SOAP communication between wsadmin tool and the server as the Digital Factory first startup after deployment takes usually more than the 180 seconds timeout, configured by default. Please, edit the /properties/soap.client.props file and change the value of com.ibm.SOAP.requestTimeout to e.g. 600 or larger, i.e.:
#----------------------------------------------------------------------# SOAP Request Timeout # # - timeout (specified in seconds [default 180], 0 implies no timeout) # #----------------------------------------------------------------------com.ibm.SOAP.requestTimeout=600
© 2002 – 2014 Jahia Solutions Group SA
Page 35 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
Ensuring that your server instance is currently running, execute the following command: Linux:
/bin/wsadmin.sh -lang jython -user password -f /digital-factory/wsadmindeploy.py Windows:
\bin\wsadmin.bat -lang jython -user password -f \digital-factory\wsadmindeploy.py The script deploys Digital Factory EAR to the server and starts it. Please, note, in Digital Factory installation 7.0.0.1 the script does not start EAR automatically. Check the last steps of the section “5.3 Deployment using UI” for how to do it via the Web UI. The deployment and first Digital Factory startup can take from 2 to 15 minutes, depending on the platform, OS and hardware characteristics.
Tip: if anything goes wrong during the application installation or startup, it is recommended to uninstall the “digital-factory” application, clean deployment directories (including the /temp and /wstemp ones) and then restart WebSphere, as some resources might not be freed until a complete restart is done before attempting the installation a second time.
© 2002 – 2014 Jahia Solutions Group SA
Page 36 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
5.3 Deployment using UI This section describes an alternative way of Digital Factory deployment using the Web-based UI (“WebSphere Integrated Solutions Console”), which in the default installation is accessible via http://localhost:9060/ibm/console. 1) Navigate to Applications -> New Application 2) Click on “New Enterprise Application” 3) Select the “Remote file system” option and specify the full path to the Digital Factory EAR file, i.e. /digital-factory/digitalfactory.ear:
4) Click “Next” and wait (be patient, WebSphere is verifying the EAR) 5) On the next screen select “Detailed - Show all installation options and parameters.” option
© 2002 – 2014 Jahia Solutions Group SA
Page 37 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
6) and click “Next” 7) On the next screen (Step 1) leave all the values like they are:
© 2002 – 2014 Jahia Solutions Group SA
Page 38 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
8) Click “Next” 9) On the Step 2 “Map modules to servers” leave the values as they are:
© 2002 – 2014 Jahia Solutions Group SA
Page 39 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
10) Click “Next” 11) On step 3 “Provide JSP reloading options for Web modules” leave values like they are:
© 2002 – 2014 Jahia Solutions Group SA
Page 40 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
12) Click “Next” 13) Step 4 “Map shared libraries”: leave unchanged:
© 2002 – 2014 Jahia Solutions Group SA
Page 41 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
14) Click “Next” 15) Step 5 “Map shared library relationships”: leave unchanged
© 2002 – 2014 Jahia Solutions Group SA
Page 42 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
16) Click “Next” 17) Step 6 “Initialize parameters for servlets”: keep as is
© 2002 – 2014 Jahia Solutions Group SA
Page 43 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
18) Click “Next” 19) Step 7 “Map resource references to resources”: keep unchanged – the Jahia module should be mapped to “jdbc/jahia” resource and use “jahiaJ2CAuthAlias” authentication data entry
© 2002 – 2014 Jahia Solutions Group SA
Page 44 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
20) Click “Next” 21) Step 8 “Map virtual hosts for Web modules”: keep unchanged
© 2002 – 2014 Jahia Solutions Group SA
Page 45 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
22) Click “Next” 23) Step 9 “Map context roots for Web modules”: keep as is or provide the “Context
Root” value in case Digital Factory is not deployed with ROOT (“/”) Web context path
© 2002 – 2014 Jahia Solutions Group SA
Page 46 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
24) Click “Next” 25) Step 10 “Map JASPI provider”: no changes needed
© 2002 – 2014 Jahia Solutions Group SA
Page 47 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
26) Click “Next” 27) Step 11 “Metadata for modules”: leave unchanged
© 2002 – 2014 Jahia Solutions Group SA
Page 48 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
28) Click “Next” 29) Step 12 “Display module build Ids”: leave as is
© 2002 – 2014 Jahia Solutions Group SA
Page 49 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
30) Click “Next” 31) Step 13 “Summary”
© 2002 – 2014 Jahia Solutions Group SA
Page 50 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
32) Click “Finish” and wait for the completion. As WebSphere is extracting the content of the EAR, it could take several minutes
© 2002 – 2014 Jahia Solutions Group SA
Page 51 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
33) After the application is installed, click on “Save”. Wait for the action to complete (this could also take a couple of minutes). 34) The application is now installed, but not started yet. 35) Navigate to “Applications -> Application Types -> WebSphere enterprise
applications” 36) Select the digital-factory application and click on “Start” button:
© 2002 – 2014 Jahia Solutions Group SA
Page 52 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
37) Digital Factory is now starting. The startup can take from 2 to 15 minutes, depending on the environment and hardware characteristics. 38) Please, monitor the /logs//SystemOut.log file for possible errors. 39) When Digital Factory startup is completed almost at the end there will be the following output message in the log file:
-----------------------------------------------------------------------Digital Factory 7.0.0.1 [Elektra] - Enterprise Distribution - Build 50061.3046 is now ready. Initialization completed in 238 seconds -----------------------------------------------------------------------40) When the startup is completed, the Digital Factory experience is ready to be discovered. The start URL will be (if the default port 9080 is used): http://:9080/. This will bring the Digital Factory login screen.
Tip: if anything goes wrong during the application installation or startup, it is recommended to uninstall the “digital-factory” application, clean deployment directories (including the /temp and /wstemp ones) and then restart WebSphere, as some resources might
© 2002 – 2014 Jahia Solutions Group SA
Page 53 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
not be freed until a complete restart is done before attempting the installation a second time.
© 2002 – 2014 Jahia Solutions Group SA
Page 54 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
6 Clustered Deployment 6.1 Running the installer Please, refer to the sections “3.1 Preparation” and “3.2 Running the installer” for instructions on downloading and starting the Digital Factory installer. Perform the installation steps, as described in the “3.3 Main installation steps” with the only difference to enable clustering on step 12, by enabling the checkbox “Provide cluster configuration for this server”:
and providing required cluster node configuration on the next step:
© 2002 – 2014 Jahia Solutions Group SA
Page 55 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
The following options are available on this screen:
Is a background job processing server – checkbox should remain enabled as the installation is done for processing server node first
IP address of this node – specify here an explicit IP address or host name (which resolves to real IP, not to the loopback 127.0.0.1) to bind server socket to (JGroups cluster communication). Leaving the value to , will force JGroups to detect the address automatically, but this is not 100% predictable process.
Server ID of this node – you can provide here a meaning unique ID for this cluster node (no spaces or special characters are allowed) or leave the value for the ID to be generated automatically.
Path to Data Store files – if you have chosen file system storage for the JCR binary files (this is the default option, contrary to storing files in the database table) you will need
© 2002 – 2014 Jahia Solutions Group SA
Page 56 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
to provide here a path to the folder, where the file data will be stored. This folder must be shared between all Digital Factory cluster nodes. After completing the installation steps, the installer will produce artifacts, described in section “3.4 Installation artifacts”. Continue with the next sections for the server configuration and deployment, starting with a Digital Factory processing node instance.
6.2 Processing node 6.2.1 Server configuration Now we proceed to the configuration of the WebSphere server instance, considering the requirements of “4.1 Prerequisites” are met, i.e. you have an existing application server profile or have created a new one. We will reference the server profile directory as further and describe the configuration procedure using wsadmin Jython script, generated by the installer. Before executing the script, you could edit it and adjust, for example, the JVM memory settings or DB connection pool properties with regard to your platform requirements. The script tries to detect the node, cell and server IDs. However, if you have multiple, you could edit the script and specify the IDs explicitly.
Ensuring that your server instance is currently running, execute the following command: Linux:
/bin/wsadmin.sh -lang jython -user password -f /digital-factory/wsadminconfigure.py Windows:
© 2002 – 2014 Jahia Solutions Group SA
Page 57 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
\bin\wsadmin.bat -lang jython -user password -f \digital-factory\wsadminconfigure.py The script forces the WebSphere server restart. Please, wait until the server is up again and continue with the steps in next section.
6.2.2 Deploying Digital Factory After configuring the server instance, we will proceed with the Digital Factory deployment (processing node) using wsadmin script. Please, increase the com.ibm.SOAP.requestTimeout value as described in beginning of the “5.2 Deployment using wsadmin script” chapter before continuing.
Ensuring that your server instance is currently running, execute the following command: Linux:
/bin/wsadmin.sh -lang jython -user password -f /digital-factory/wsadmindeploy.py Windows:
\bin\wsadmin.bat -lang jython -user password -f \digital-factory\wsadmindeploy.py The script deploys Digital Factory EAR to the server and starts it. The deployment and first Digital Factory startup can take from 2 to 15 minutes, depending on the platform, OS and hardware characteristics. Please, monitor the logs and access the Web application to ensure the startup and initialization are successful.
© 2002 – 2014 Jahia Solutions Group SA
Page 58 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
Now stop the server instance to proceed with the next steps for setting up Digital Factory nonprocessing nodes.
6.3 Non-processing node Assuming that you did the configuration, deployment and startup of the Digital Factory processing node, as described in previous chapter “6.2 Processing node” we can now continue setting up a non-processing node to join the cluster.
6.3.1 Preparation Assure that you have stopped the Digital Factory processing node. Copy the whole Digital Factory installation directory () from processing node to your browsing node server. Now perform the steps on the browsing server, described in the following sections. The will reference here the Digital Factory installation directory on the browsing node.
6.3.1.1 Adjust clustering configuration Open the /digitalfactory/config/jahia/jahia.node.properties configuration file and adjust the following settings:
cluster.node.serverId – provide here a unique cluster node ID, say browsing-1 (should be different on all nodes in the cluster)
processingServer – uncomment this entry and set the value to false
cluster.tcp.bindAddress – specify here the IP address or host name to bind the JGroups service to
© 2002 – 2014 Jahia Solutions Group SA
Page 59 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
cluster.tcp.bindPort – if needed, uncomment this entry to override the default bind port (7870)
6.3.1.2 File data store If you are using file system based data store for JCR file storage, ensure the datastore folder from processing node is shared and available on this browsing node at the same path. If the share path is different from the processing node, please, adjust the “jackrabbit.datastore.path” value in the /digital-factory/config/jahia/jahia.properties file.
6.3.1.3 Delete OSGi bundle cache Delete the bundle cache folder /digital-factory/data/bundles-deployed.
6.3.1.4 Adjust paths (in case of different path only) If the absolute path of the folder on the browsing node differs from the original location on processing node, additional steps are required. If the path is the same, please, skip this section and continue with the next one.
Adjust the value of the “jahiaVarDiskPath” in the /digitalfactory/config/jahia/jahia.properties file to reflect the path to your Digital Factory data folder.
Adjust the values of “jahiaSharedLibrariesPath”, “jahiaConfigurationPath” and “jdbcProviderClassPath” in /digital-factory/wsadminconfigure.py and the value of “jahiaEarPath” in the /digital-factory/wsadmin-deploy.py scripts to reflect the absolute path to the on this server.
6.3.1.5 Update the journal local revision (DF 7.0.0.2 only) This step is only needed, if you are running Digital Factory 7.0.0.2. If you are on 7.0.0.3 or later, this section can be skipped. © 2002 – 2014 Jahia Solutions Group SA
Page 60 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
Please, execute the following SQL insert statement against your DB schema, replacing the with your value (the one, which is configured in jahia.node.properties in the cluster.node.serverId value for this browsing node):
insert into JR_J_LOCAL_REVISIONS (JOURNAL_ID, REVISION_ID) select '', REVISION_ID from JR_J_GLOBAL_REVISION The preparation of the browsing server data and configuration is finished, you can proceed with the next sections.
6.3.2 Server configuration Perform the configuration of the WebSphere server for this browsing instance in a similar way to processing one (see section “6.2.1 Server configuration” for details).
6.3.3 Deploying Digital Factory Perform the deployment of the Digital Factory instance on this browsing instance in a similar way to processing one (see section “6.2.2 Deploying Digital Factory” for details).
6.3.4 Verification If the above steps are completed successfully, you should now have the browsing instance initialized and running. Please, start now the processing instance and verify that two instances build the cluster, by checking the logs for messages like:
DEBUG [GMS] - rqa11-32026: installing view … and also checking the cluster status in the tools area: http://[server]:[port]/tools/cluster.jsp
© 2002 – 2014 Jahia Solutions Group SA
Page 61 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
6.4 Further non-processing nodes You can install additional non-processing nodes at any time following the procedure, described in the chapter “6.3 Non-processing node”.
© 2002 – 2014 Jahia Solutions Group SA
Page 62 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
7 Updating Digital Factory Using Fix Applier 7.1 Prerequisites Before executing this procedure, make sure you have a full backup of your installation (DB data + filesystem data), as you will need it if any problem occurs during this procedure. Please, download the appropriate Fix Applier package from the http://www.jahia.com/customerextranet/digital-factory-jahia-7-0 that you would like to apply to your Digital Factory installation. We assume here the following artifacts and paths: 1) the last version of the installed EAR file: /digitalfactory/digitalfactory.ear1 2) the configuration folder: /digital-factory/config 3) the runtime data folder: /digital-factory/data The following procedure describes the way to apply a hotfix on a packaged EAR file2.
7.2 Standalone Digital Factory installation This section describes the upgrade procedure for a standalone (single-node) Digital Factory installation.
1
Alternatively, you could export the EAR file from your WebSphere instance.
2
If you experience any issues with that approach, you could unpack the content of the digitalfactory.ear file and then
the content of the contained jahia.war file. Apply the hotfix on the extracted jahia.war content and package back the content into the jahia.war and everything into digitalfactory.ear file.
© 2002 – 2014 Jahia Solutions Group SA
Page 63 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
Please, follow the steps here to perform the update: 1) Use WebSphere Web console and navigate to “Applications -> Application Types -> WebSphere enterprise applications” 2) Check the “digital-factory” application and click on “Uninstall”
3) Click “Save” to save the changes 4) Shut the WebSphere server completely 5) Execute the Fix Applier package passing the required parameters (replace the with the corresponding absolute path and the name of the fix applier file with the appropriate one):
java -jar EnterpriseDigitalFactory7.0_7.0.0.0_r49489_to_7.0.0.1_r50061.jar --target /digital-factory/digitalfactory.ear --data /digital-factory/data --config /digitalfactory/config 6) Follow the fix applier instructions and complete the operation 7) Delete the content of the WebSphere temporary folders /temp and /wstemp (keeping the folders themselves) 8) Ensure that there are no “rests” of the digital-factory.ear left under /installedApps// 9) Start your WebSphere server 10) Deploy and start the updated digital-factory.ear using either the wsadmindeploy.py wsadmin script (see “5.2 Deployment using wsadmin script”) or the WebSphere Web Console (see “5.3 Deployment using UI”)
© 2002 – 2014 Jahia Solutions Group SA
Page 64 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
11) Wait for the Digital Factory to start up monitoring the /logs//SystemOut.log file for possible errors. 12) If the Fix Appliers “How to upgrade” implies the full repository content re-indexing, please, use the “Search engine management” Tool (http://[server]:[port]/tools/search.jsp) and click on “Repository re-indexing - Do repository re-indexing on the next Jahia start”. Stop and start your Digital Factory server again. During startup, it will perform a complete repository content re-indexing. 13) Your Digital Factory instance is now upgraded.
7.3 Clustered Digital Factory installation In case of a clustered (multi-node) Digital Factory installation, please follow the steps, described in the next sections.
7.3.1 Uninstall Digital Factory Ensure you have the latest version of the digitalfactory.ear file that is deployed on the servers (see section “7.1 Prerequisites”) before uninstalling the Digital Factory. Execute the following actions on all cluster nodes: 1) Use WebSphere Web console and navigate to “Applications -> Application Types -> WebSphere enterprise applications” 2) Check the “digital-factory” application and click on “Uninstall”
3) Click “Save” to save the changes
© 2002 – 2014 Jahia Solutions Group SA
Page 65 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4) Shut the WebSphere server down completely 5) Delete the content of the WebSphere temporary folders /temp and /wstemp (keeping the folders themselves) 6) Ensure that there are no “rests” of the digitalfactory.ear left under /installedApps// 7) Start your WebSphere server back Now begin with the upgrade procedure, starting with the processing node first.
7.3.2 Processing node Assuming the Digital Factory is already uninstalled, as described in previous section “7.3.1 Uninstall Digital Factory”. Then, please, perform the operations: 1) Execute the Fix Applier package passing the required parameters (replace the with the corresponding absolute path and the name of the fix applier file with the appropriate one):
java -jar EnterpriseDigitalFactory7.0_7.0.0.0_r49489_to_7.0.0.1_r50061.jar --target /digital-factory/digitalfactory.ear --data /digital-factory/data --config /digitalfactory/config 2) Follow the fix applier instructions and complete the operation 3) Ensure your WebSphere server is started 4) Deploy and start the updated digitalfactory.ear using either the wsadmindeploy.py wsadmin script (see “5.2 Deployment using wsadmin script”) or the WebSphere Web Console (see “5.3 Deployment using UI”) 5) Wait for the Digital Factory to start up monitoring the /logs//SystemOut.log file for possible errors. 6) If the Fix Appliers “How to upgrade” implies the full repository content re-indexing, please, use the “Search engine management” Tool (http://[server]:[port]/tools/search.jsp) and click on “Repository re-indexing - Do repository re-indexing on the next Jahia start”. Stop and
© 2002 – 2014 Jahia Solutions Group SA
Page 66 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
start your Digital Factory server again. During startup, it will perform a complete repository content re-indexing. 7) Your Digital Factory instance is now upgraded. 8) Continue with the procedure for upgrading non-processing nodes now (see next section).
7.3.3 Non-processing node For each non-processing node, you should repeat the upgrade procedure, described in the prevision section “7.3.2 Processing node”. If the Fix Appliers “How to upgrade…” implies full repository content re-indexing with the upgrade, you could take the indexes, already re-generated by the processing node (on the step “12)”). Please, refer to the section “9.3 Copying repository indexes to other cluster nodes” for details.
© 2002 – 2014 Jahia Solutions Group SA
Page 67 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
8 Portlet Deployment As Digital Factory can also use portlets as content elements, we detail here the procedure on how to deploy a portlet application into the WebSphere. Please note that the verified and tested deployment scenario for portlet applications is to be deployed into the Digital Factory EAR file and not outside as a separate deployment modules.
8.1 Prerequisites Due to a known WebSphere bug with path info and response.sendRedirect() (http://www01.ibm.com/support/docview.wss?uid=swg1PK23779) a special property needs to be set for the Web container for portlet actions to work, as they are using redirects. Please, refer to the section “4.3.2 Web container” to ensure that this property is set. Continue with the next section.
8.2 Preparing a portlet Web application A portlet Web application needs to be prepared to be deployed into Digital Factory’s portlet container: 1) entries will be added into the Web application deployment descriptor (METAINF/web.xml) 2) portlet tag libraries will be added into the WAR (WEB-INF/portlet.tld and WEBINF/portlet_2_0.tld) The preparation can be done using a Digital Factory instance, which is running on WebSphere. 1) Go to the Digital Factory Administration -> System components -> Portlets 2) Click on “Deploy new portlets” button in the toolbar 3) Select the portlet WAR file you would like to prepare © 2002 – 2014 Jahia Solutions Group SA
Page 68 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4) Click on “Prepare portlet for deployment”
5) The WAR will be processed and the link to download the prepared WAR will be displayed:
6) Download and save that WAR file. This artifact will be deployed into the Digital Factory EAR file: see next section.
© 2002 – 2014 Jahia Solutions Group SA
Page 69 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
8.3 Deployment steps In our example we deploy the Pluto Test Suite Web application (filename: pluto-testsuite-
2.0.2-websphere.war; module path: “pluto-testsuite.war”) Here are the steps to deploy a prepared (see previous section) portlet Web application into Digital Factory. 1) Navigate to “Applications -> Application Types -> WebSphere enterprise
applications” 2) Select the digital-factory application and click on “Update” button 3) Select the “Replace or add a single module” option 4) Specify the module path. This module path can be used later to update the module:
© 2002 – 2014 Jahia Solutions Group SA
Page 70 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
5) Click “Next” 6) On the next screen choose “Detailed - Show all installation options and
parameters.” Option
© 2002 – 2014 Jahia Solutions Group SA
Page 71 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
7) Click “Next” 8) The next screen is “Application Security Warnings”
9) Click “Continue” 10) On the Step 1 “Select installation options” screen no changes are needed
© 2002 – 2014 Jahia Solutions Group SA
Page 72 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
11) Click “Next” 12) Step 2 “Map modules to servers”: keep the values as they are
© 2002 – 2014 Jahia Solutions Group SA
Page 73 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
13) Click “Next” 14) On the Step 3 “Provide JSP reloading options for Web modules” you could adjust the “JSP reload interval in seconds” to e.g. 180 seconds
© 2002 – 2014 Jahia Solutions Group SA
Page 74 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
15) Click “Next” 16) Step 4 “Map shared libraries”: no changes are needed
© 2002 – 2014 Jahia Solutions Group SA
Page 75 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
17) Click “Next” 18) Step 5 “Map shared library relationships”: no changes
© 2002 – 2014 Jahia Solutions Group SA
Page 76 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
19) Click “Next” 20) Step 6 “Initialize parameters for servlets”: nothing to adjust
© 2002 – 2014 Jahia Solutions Group SA
Page 77 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
21) Click “Next” 22) Step 7 “Map virtual hosts for Web modules”: no changes needed
© 2002 – 2014 Jahia Solutions Group SA
Page 78 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
23) Click “Next” 24) Step 8 “Map context roots for Web modules”: specify here the context path for your portlet Web application
© 2002 – 2014 Jahia Solutions Group SA
Page 79 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
25) Click “Next” 26) Step 9 “Map JASPI provider”: leave unchanged
© 2002 – 2014 Jahia Solutions Group SA
Page 80 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
27) Click “Next” 28) Step 10 “Display module build Ids”: no changes
© 2002 – 2014 Jahia Solutions Group SA
Page 81 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
29) Click “Next” 30) Step 11 “Summary”: summary of the installation options is displayed
© 2002 – 2014 Jahia Solutions Group SA
Page 82 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
31) Click “Finish” 32) The EAR update process is started now. Please, wait for it to complete. 33) Do not click on “Save”, but rather on “Manage Applications”
© 2002 – 2014 Jahia Solutions Group SA
Page 83 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
34) Click on “digital-factory” in the Enterprise Applications screen to go into its configuration 35) Click on “Manage Modules” 36) In the module click on the currently installed portlet Web application to open module configuration page 37) Here select in the “Class loader order” the “Classes loaded with local class loader
first (parent last)” option
© 2002 – 2014 Jahia Solutions Group SA
Page 84 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
38) Click on “OK” 39) And now perform the “Save” into master configuration. The operation will take time as it restarts the Digital Factory application. 40) When the Digital Factory will be up, go to the Digital Factory Administration ->
System components -> Portlets and verify that the portlets were correctly deployed:
© 2002 – 2014 Jahia Solutions Group SA
Page 85 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
41) Portlet deployment is now completed.
© 2002 – 2014 Jahia Solutions Group SA
Page 86 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
9 Frequently Asked Questions (FAQ) 9.1 Debugging in WebSphere You could activate remote debugging (JPDA) support in WebSphere on the “Java Virtual
Machine” option screen, like described in section “4.3.1 JVM options”. After activating this option, please, restart your server. Note, please, that the activated JPDA could slow down the server, sometimes significantly. After that you will be able to connect your IDE to the WebSphere using the remote debug configuration (default port is 7777). Here is an example of a remote debugging configuration in IntelliJ IDEA:
© 2002 – 2014 Jahia Solutions Group SA
Page 87 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
9.2 Mail setup with Gmail If you try to configure Jahia with a Gmail SMTP SSL configuration, you might get the following error in the logs:
[9/10/14 11:58:23:022 CEST] 000000c1 WSX509TrustMa E CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN "CN=smtp.gmail.com, O=Google Inc, L=Mountain View, ST=California, C=US" was sent from target host:port "smtp.gmail.com:465". The signer may need to be added to local trust store "/opt/IBM/WebSphere/AppServer/profiles/df/config/cells/rqa11N ode01Cell/nodes/rqa11Node01/trust.p12" located in SSL configuration alias "NodeDefaultSSLSettings" loaded from SSL configuration file "security.xml". The extended error message from the SSL handshake exception is: "PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by OU=Equifax Secure Certificate Authority, O=Equifax, C=US is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error". [9/10/14 11:58:23:023 CEST] 000000c1 SystemOut O [9/10/14 11:58:23:023 CEST] 000000c1 SystemOut O CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN "CN=smtp.gmail.com, O=Google Inc, L=Mountain View, ST=California, C=US" was sent from target host:port "smtp.gmail.com:465". The signer may need to be added to local trust store "/opt/IBM/WebSphere/AppServer/profiles/df/config/cells/rqa11Node01Cell/nodes/rqa11Node01/trust.p12" located in SSL configuration alias "NodeDefaultSSLSettings" loaded from SSL configuration file "security.xml". The extended error message from the SSL handshake exception is: "PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by OU=Equifax Secure Certificate Authority, O=Equifax, C=US is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error". [9/10/14 11:58:23:023 CEST] 000000c1 SystemOut O [9/10/14 11:58:23:023 CEST] 000000c1 SystemOut O [9/10/14 11:58:23:023 CEST] 000000c1 SystemOut O CWPKI0428I: The signer might need to be added to the local trust store. You can use the Retrieve from port option in the administrative console to retrieve the certificate and resolve the problem. If you determine that the request is trusted, complete the following steps: 1. Log into the administrative console. 2. Expand Security and click SSL certificate and key management. Under Configuration settings, click Manage endpoint security configurations. 3. Select the appropriate outbound configuration to get to the (cell):rqa11Node01Cell:(node):rqa11Node01 management scope. 4. Under Related Items, click Key stores and certificates and click the NodeDefaultTrustStore key store. 5. Under Additional Properties, click Signer certificates and Retrieve From Port. 6. In the Host field, enter smtp.gmail.com in the host name field, enter 465 in the Port field, and smtp.gmail.com_cert in the Alias field. 7. Click Retrieve Signer Information. 8. Verify that the certificate information is for a certificate that you can trust. 9. Click Apply and Save.
To fix this problem, simply follow these steps: 1. Log into the administrative console. 2. Expand Security and click SSL certificate and key management. Under Configuration settings, click Manage endpoint security configurations. 3. Select the appropriate outbound configuration to get to the (cell):*Node01Cell:(node):*Node01 management scope. 4. Under Related Items, click Key stores and certificates and click the NodeDefaultTrustStore key store. 5. Under Additional Properties, click Signer certificates and Retrieve From Port. © 2002 – 2014 Jahia Solutions Group SA
Page 88 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
6. In the Host field, enter smtp.gmail.com in the host name field, enter 465 in the Port field, and smtp.gmail.com_cert in the Alias field. 7. Click Retrieve Signer Information. 8. Verify that the certificate information is for a certificate that you can trust. 9. Click Apply and Save. 10. Restart the WebSphere node
9.3 Copying repository indexes to other cluster nodes Starting with Digital Factory 7.0.0.3 the process of manual synchronization of repository indexes between cluster nodes became easier. This manual synchronization is not needed during the runtime, but could be quite useful in the following cases:
A cluster node was down for quite a long time (“cold standby” case) and its startup should be made fast avoiding to replay the repository changelog journal (the journal records all the content modifications on other cluster nodes, which needs to be replayed by this one to make the index up-to-date).
Indexes of one node are physically corrupted and need to be replaced by “healthy” indexes from another node in the cluster.
Assuming a full repository content re-indexing was performed on a processing node (say, during the Digital Factory upgrade process) and you would like to synchronize those indexes to other cluster members.
Please, follow the step to replicate the indexes from one node (source) to the other (target): 1) Shut the source server down and wait for a shutdown to complete 2) Shut the target server down 3) Delete the indexes folders on the target server:
/digital-factory/data/repository/index
/digital-factory/data/repository/workspaces/default/index
/digital-factory/data/repository/workspaces/live/index
© 2002 – 2014 Jahia Solutions Group SA
Page 89 / 91
Digital Factory 7.002. Installation Guide for WebSphere 8.5.5
4) Copy the corresponding indexes folders from the source server to the target. You could copy the content of the /digital-factory/data/repository to the /digital-factory/data/repository, omitting the datastore folder. 5) Copy the file /digital-factory/data/repository/revisionNode to the /digital-factory/data/repository folder. 6) You can start now the source and the target nodes.
© 2002 – 2014 Jahia Solutions Group SA
Page 90 / 91
Jahia Solutions Group SA 9 route des Jeunes, CH-1227 Les acacias Geneva, Switzerland http://www.jahia.com
