Install guide for Websphere 7.0

(1)

D

OCUMENTATION

Install guide for Websphere 7.0

Jahia EE v6.6.1.0

Jahia’s next-generation, open source CMS stems from a widely acknowledged

vision of enterprise application convergence – web, document, search, social and

portal – unified by the simplicity of web content management.

Jahia Solutions Group SA 9 route des Jeunes,

CH-1227 Les acacias Geneva, Switzerland

(2)

Page 2 / 46

DOCUMENTATION ... 1

1 Supported platforms ... 3

2 Requirements ... 3

3 Installation instructions ... 3

3.1 Configuring Jahia ... 3

3.2 Shared libraries deployment ... 4

3.3 Server configuration ... 5

3.4 Data source setup ... 8

3.5 Deploying in WebSphere ... 20

3.6 Jahia configuration externalization ... 37

3.7 Portlet deployment ... 38

4 Debugging in WebSphere ... 43

(3)

1 Supported platforms

The following procedure has only been tested with the 64-bit (because of memory requirements) version 7.0.0.23 of the IBM WebSphere Application Server platform. 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 Requirements

- WebSphere Application Server 7.0.0.23 or more recent fix pack

- Fully updated WebSphere Application Server JDK (non IBM JDKs are not supported)

- A supported 64-bit operating system such as RedHat Enterprise Linux 5 (see release notes for support of more recent versions), Windows XP. (CentOS 5 is known to work but is not officially supported). Ubutun/Debian or other Linux distributions are not recommended and not officially supported.

- 4GB RAM (minimum), 8GB RAM (recommended)

- At least 20GB hard disk space (including WebSphere install)

In general it is highly recommended to stick as much as possible to the recommended platforms. For more recent information, check the IBM WebSphere platform requirements for version 7.0.

3 Installation instructions

3.1 Configuring Jahia

1. Download the Jahia Enterprise package

2. Run the graphical installer on any platform, remove the option to use a bundled Tomcat package,

(4)

Page 4 / 46

WebSphere server. Once the installer is finished in your install directory you should find a file named ROOT.ear and a file named shared-libraries.zip.

This completes Jahia’s preparation for deployment on Websphere. We can now move to the setup of the server.

3.2 Shared libraries deployment

Extract the shared-libraries.zip ZIP file in the folder of your choice (we recommend something like

/opt/IBM/WebSphere/AppServer/shared-libraries), and declare a new shared library : in “Environment” /

“Shared Libraries”, select server scope and click on “new”, and then specify the folder where you have copied the libs in the “Classpath” input and use the name “Jahia Shared Libraries” for the library name (this will make automatic bindings work transparently). Make sure you click “OK” and then “Save” to persist the changes to the master configuration. When deploying the application, it will have to reference this library (the Jahia application itself, so that the library will be shared by all the modules from the EAR, including the Jahia module). Also copy the:

portlet-api_2.0_spec-1.0.jar

to the directory :

AppServer/lib/ext/

The result should look something like this:

(5)

3.3 Server configuration

3.3.1 JVM

Open Servers -> Application Servers -> <server> -> Java and process management -> Process definition ->

Java Virtual Machine

(6)

Page 6 / 46

Warning: performing the above steps will not work with the 32-bit version of WebSphere (it will no longer start and you will be forced to hack configuration files to retrieve a normal state). As 3GB RAM are

required for a proper execution of Jahia, only the 64-bit version of WebSphere may be used when installing Jahia.

(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 “Debugging in WebSphere” section later in this document.

(7)

3.3.2 Web container

Open Servers -> Application Servers -> <server> -> Web Container Settings and click on the “Web container” link

 Then click on the “Custom Properties” link

 Select New and then enter "com.ibm.ws.webcontainer.invokeFiltersCompatibility" as the property name and "true" as the value as illustrated in the screenshot below:

Do the same for the following properties :

com.ibm.wsspi.jsp.enabledoublequotesdecoding = true com.ibm.wsspi.jsp.evalquotedandescapedexpression = true

You should have the following result:

(8)

Page 8 / 46

Those server configurations require restarting the application server. You can delay this restart, but you will have to do it at least once before starting Jahia.

Tip: to restart the server you will probably use a command line like the following:

/opt/IBM/WebSphere7/AppServer/profiles/AppSrv01/bin/stopServer.sh server1 ; /opt/IBM/WebSphere7/AppServer/profiles/AppSrv01/bin/startServer.sh server1

3.4 Data source setup

You need to define a data source in your Application server for Jahia to be able to talk to the database server. This data source will be further mapped on the resources declared in your Jahia application.

3.4.1 JDBC Provider creation

You need to create a JDBC provider before being able to create a datasource to your database server. If you want to use a MS SQL Server database, you can use a JDBC Provider included with your WAS server, and so skip directly the following points.

For other database providers, you will have to create manually your JDBC Provider:

(9)

 Copy the database driver jar file(s) into the AppServer/lib directory (if there isn’t already one that’s suiteable). For Oracle, use the following driver: ojdbc5-11.2.0.2.0.jar and orai18n-11.2.0.2.0 in WebSphere configuration and not the ojdbc14.jar or ojdbc6.jar ones. You can find the

recommended Oracle driver JARs in Jahia’s ROOT.ear/jahia.war/WEB-INF/lib directory

 Open Resources / JDBC / JDBC Providers, specify Server scope (Node=node_name, Server=server_name)

 Click on “New” button

 Fill in the screen as illustrated below, then click “Next”:

 In the next screen, specify the path to the directory where the jdbc driver is located, enter

(10)

Page 10 / 46

Please note that the driver is not yet the correct one, we will adjust this later.

(11)

 On this screen, click “Finish”:

 You’ll end up on the following screen. Before saving, we will click on the “Oracle JDBC Driver”

provider we have just add it and modify it to use a different version of the driver (the one provided with Jahia):

(12)

Page 12 / 46

 You should now be on the following screen :

(13)

 We will now modify the “Class path” to use the latest version by inputting the following values:

${ORACLE_JDBC_DRIVER_PATH}/ojdbc5-11.2.0.2.0.jar

${ORACLE_JDBC_DRIVER_PATH}/orai18n-11.2.0.2.0.jar

 Click “OK” and then click “Save” to the master configuration.

3.4.2 Data source creation

3.4.2.1 Authentication alias creation

You need to define the login and password that will be used to connect to your database instance.

(14)

Page 14 / 46

 Open Security / Global security / Java Authentication and Authorization Service / J2C authentication data

 Uncheck the “Prefix new alias names” option then click on Apply

 Click on “New…” (double-check the “Prefix new alias names” is not activated)

 Fill in all required fields on screen, entering your database user and password information. Make sure you use the following alias name “jahiaJ2CAuthAlias”, as Jahia’s default IBM deployment files reference that alias name, making the mapping process smoother for automated deployments:

(15)

 Click on “Ok” and then “Save”:

3.4.2.2 Data source creation

You are now ready to create your data source. The Jahia application requires it to have JNDI name jdbc/jahia.

 Open Resources / JDBC / Data sources

 Specify Server scope

(16)

Page 16 / 46

 Click on “New…”

 Specify an explicit name for your Data source, specify the required JNDI name “jdbc/Jahia”, and select your previously defined authentication alias:

(17)

 Click on Next

 Select the JDBC Provider you want to use (use the one you have created previously or an existing one, you shouldn’t need to create a new one at this point):

(18)

Page 18 / 46

 Fill in the next screen with your URL to your database, select the appropriate helper for your Oracle version and make sure you uncheck the “Use this data source in container managed persistence (CMP)” option.

 Click on Next

(19)

 Select the Auth alias we created previously in the “Component-managed authentication alias”

drop-down, it should be named jahiaJ2CAuthAlias:

 Click on “Next”

 Your summary screen should look like this:

(20)

Page 20 / 46

 Click “Save” to save the changes to the master configuration

 You can now test the created connection by selecting it and clicking the “Test connection” button. If it works you should see this message:

If something went wrong, go back to check the settings.

3.5 Deploying in WebSphere

You are now ready to deploy Jahia into WebSphere. Here are the steps to achieve this:

(21)

1. Important: if you deploy Jahia in the root context, and if you have kept the “Default application”

installed by WebSphere when creating your WebSphere profile, remove it from the server, as it will interfere with the installation.

2. Deploy using the Applications->New Application screen.

3. Select “New Enterprise Application”

4. Upload the ROOT.ear file we generated previously, or copy it to the disk of the WebSphere Server and use the remote file system selection to point to it.

(22)

Page 22 / 46

6. Selected “Detailed” and then click “Next”:

(23)

7. On the security settings screen leave it as it is and click “Continue”:

8. On the “Installation options” screen we will make the following input:

- Change the name of the application” to “jahia"

(24)

Page 24 / 46

Leave all the rest at the default values, you should have the following settings:

9. Click “Next”

(25)

10. On the “Map modules to servers” screen don’t change anything simply click “Next”

11. On the “Provide JSP reloading options for Web modules” screen change the default value of 60 seconds to 120 seconds as Jahia has a lot of JSPs and scanning them too often is not a good idea (on

(26)

Page 26 / 46

production servers it is even recommended to set value higher):

12. Click “Next”

13. On the “Map shared libraries” screen, check the checkbox next to the “jahia” application :

and then click the “Reference shared libraries” button.

14. On the next screen move the “Jahia shared libraries” from “Available” to “Selected” by clicking on

the right arrow:

(27)

and then click “Ok”

15. Your screen should now look like this:

You can then click “Next”.

(28)

Page 28 / 46

16. On the “Map shared library relationships” screen, leave everything as it is and click “Next”:

(29)

17. On the screen “Initialize parameters for servlets” keep the defaults and click “Next”:

(30)

Page 30 / 46

18. On the screen “Map resource references to resources” select the checkbox and click the “Modify

resource authentication method”:

19. A sub-screen to select the authentication method will appear. Select the “Use default method”

radio button and select the Authentication alias we have setup previously. Once that is done, click the “Apply” button (make sure you had checked the checkbox next to the “Jahia” module in the

(31)

previous step):

20. Back to the previous screen, make sure that in the Authentication data entry you have the authentication alias you selected, otherwise this means you haven’t applied the authentication

(32)

Page 32 / 46

settings properly:

(33)

22. On the “Map virtual hosts for Web modules” leave the defaults and click “Next”:

(34)

Page 34 / 46

23. On the “Map context roots for Web modules” make sure the Context root that is selected corresponds to the one you have used when setting up Jahia with the installer:

(35)

25. Your summary should look like this:

26. If all is ok, click “Finish”. This step might take some time to complete, that’s normal since it is actually unpacking the application.

(36)

Page 36 / 46

27. You should see after installation is completed a screen such as this one:

28. Click “Save”. The application is now installed but not started.

29. Go to Applications / Application Types / WebSphere enterprise applications and select the Jahia

resource and click the “Start” button:

30. Check the logs to see if no errors are appearing (do not assume that if you see a message “Jahia application has started successfully” that there weren’t any errors). You can do this by using a

(37)

command similar to this one:

tail -f /opt/IBM/WebSphere7/AppServer/profiles/AppSrv01/logs/server1/SystemOut.log

The initial setup will take a few minutes to complete (, so make sure you wait until you see the

following message in the logs:

Jahia is now ready. Initialization completed in 514 seconds

31. Then connect to Jahia using the url: http://websphere_server_ipaddress:9080 and you will access the Jahia login screen.

Tip: if anything goes wrong during the application install, it is recommended to uninstall the “Jahia”

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.

3.6 Jahia configuration externalization

This section focuses on how to deploy the externalized configuration in WebSphere, and how to reference it by the deployed Jahia application. For more information about the externalized configuration itself, please refer to the corresponding documentation.

1. Create a folder on your server for your configuration files (for example /app/jahia/externalizedConf/ )

2. Create in this folder the following subfolders structure: org/jahia/config/ (to have /app/jahia/externalizedConf/org/jahia/config/ )

3. Create a shared library for this externalized configuration: in “Environment” / “Shared Libraries”, select server scope and click on “new”, and then specify the path of your configuration folder in the

“Classpath” input. (/app/jahia/externalizedConf/ in the example)

4. Open “Applications” / “Enterprise applications” / “Jahia” / “Shared library references” and map your shared library on the Jahia module (not the Jahia application).

(38)

Page 38 / 46

5. You can now put your externalized configurations inside the config/ folder.

If you are using a clustered WebSphere, you can export your Jahia application from the WebSphere console after having mapped your shared library on the Jahia Module. In Jahia.ear/META-

INF/ibmconfig/cells/defaultCell/applications/defaultApp/deployments/defaultApp/deployment.xml , you will have a reference to the shared library. This means that before deploying your generic EAR inside the WebSphere cluster, you will have to create the same shared library on each of your application servers, but with different configuration files. Then you can deploy your EAR.

3.7 Portlet deployment

As Jahia can also use portlets as content elements, we detail here the procedure on how to deploy a portlet application into the WebSphere application server platform. Please note that Jahia does not support portlets packaged inside a separate JEE application, they must be deployed into the same JEE application as Jahia.

Here are the steps to deploy a portlet into Jahia:

1. As there is a known bug in WebSphere 7.0 concerning redirects (http://www-

01.ibm.com/support/docview.wss?uid=swg1PK23779), and as these are used for portlet actions, you must first change a setting in the configuration of the server. To do this, go to the integrated console (http://websphere_server_ipaddress:9060/ibm/console/) , login, and then navigate to :

(39)

Servers -> Application Servers -> YOURSERVERINSTANCENAME -> Container settings -> Web container settings -> Web container -> Additional properties -> Custom properties and add a property called “com.ibm.ws.webcontainer.RedirectWithPathInfo” and set it’s value to true. You screen should look like this (including other settings previously setup when configuring the server for Jahia):

2. Now save the settings to the master configuration. You must then stop and restart the WebSphere server for the changes to take effect (using the stopServer.sh and startServer.sh scripts).

3. Follow the existing “Portlet Deployment Guide” to prepare your portlets for deployment inside Jahia

4. If your portlet references the following URI in their taglib: http://java.sun.com/portlet_2_0 you must then first add the TLD (available here:

http://svn.apache.org/viewvc/portals/pluto/tags/JSR286-RI/pluto-

taglib/src/main/resources/META-INF/portlet_2_0.tld?revision=619585 ) in your portlet application, and reference it in the web.xml of the portlet application. Make sure you copy the file in the proper directory (in the example below it’s in tld/) and that you rename it to something else than

portlet_2_0.tld to avoid conflict. This is also necessary for the pluto-testsuite portlet standard test.

Your web.xml should reference it as in the example below:

(40)

Page 40 / 46

5. Add to the beginning of the web.xml (in the context-param section) file included in the portlet application the following lines:

<context-param>

<param-name>com.ibm.websphere.portletcontainer.PortletDeploymentEnabled</param- name>

<param-value>false</param-value>

</context-param>

6. We strongly recommended that you pass your web.xml and portlet.xml files in a XSD validator before deploying on WebSphere, this will prevent any problems that may be due to a syntax error.

You can use any online XSD validator such as http://www.xmlforasp.net/schemavalidator.aspx 7. Click on “Enterprise Application”

8. Check the checkbox in front of “Jahia” and click on update button

9. Select “Replace or add single module”, select your *.war file and specify the name of the archive file to install (you can later use this name to replace the same module with another version for

(41)

example). In the following screenshot, portlet-testsuite.war is used as an example. Make sure you also enter the path for the value “Specify the path beginning…”

10. Click “Next”, and choose the detailed path.

11. Click the “Next” buttons until you get to the “Map context roots for Web modules” screen. In there make sure you replace the “/” with a context root matching the portlet application name, such as

(42)

Page 42 / 46

“pluto-testsuite” in our example.

12. Your summary screen should look like this:

13. Click on “Finish” and “Save” link.

14. In Jahia, go into the “Manage Portlets” screen that will trigger an internal sync with the server. Your portlet application should then appear and you can use it within the server.

(43)

4 Debugging in WebSphere

1. In Servers -> Server Types -> WebSphere Application Servers, click on “server1”

2. Then into Server Infrastructure -> Java and Process Management click on “Process definition”.

3. Click on “Additional properties” -> Java Virtual Machine

(44)

Page 44 / 46

4. Check the “Debug mode” checkbox and make sure that the port in the debug arguments is set to 7777

5. Click on “OK”

6. Save to the master configuration

7. Restart WebSphere. When running in debug mode JVM execution can be much slower!

8. In your IDE, do NOT use the WebSphere integration, simply setup a Java remote debugging session on port 7777.

(45)

9. Here is an example of a remote debugging configuration in Intellij IDEA:

(46)

Jahia Solutions Group SA

9 route des Jeunes,

CH-1227 Les acacias

Geneva, Switzerland

http://

Install guide for Websphere 7.0

D