documentation configuration and fine tuning guide … · documentation configuration and fine...

Jahia

9 route des Jeunes, CH-1227 Les acacias Geneva, Switzerland

www.jahia.com The Company website

www.jahia.org The Community website

Documentation

Configuration and fine tuning Guide Jahia EE v6.1 Jahia delivers the first Web Content Integration Software

by combining Enterprise Web Content Management with

Document and Portal Management features.

May 2011

September 2009

of 91

www.jahia.com > The Company website www.jahia.org > The Community website

Summary Summary .............................................................................................................................................................. 2 1 Overview ....................................................................................................................................................... 6

1.1 Introduction ............................................................................................................................................ 6 1.2 What’s in this documentation? ............................................................................................................... 6

2 Configuration ................................................................................................................................................. 7 2.1 Installation .............................................................................................................................................. 7 2.2 Preparing your system ........................................................................................................................... 8

2.2.1 Under Windows............................................................................................................................... 8 2.2.2 Under Linux..................................................................................................................................... 9 2.2.3 Under Solaris .................................................................................................................................. 9 2.2.4 Default Embedded Java application Server.................................................................................... 9 2.2.5 Default Embedded Database.......................................................................................................... 9 2.2.6 Tomcat .......................................................................................................................................... 10

2.3 Websphere Application Server 6.1.x.................................................................................................... 13 2.3.1 Supported platforms...................................................................................................................... 13 2.3.2 Known issues................................................................................................................................ 14 2.3.3 Configuring Jahia .......................................................................................................................... 14 2.3.4 Packaging for Websphere............................................................................................................. 15 2.3.5 Websphere Filter configuration ..................................................................................................... 18 2.3.6 Data sources definition ................................................................................................................. 20 2.3.7 Deploying in Websphere............................................................................................................... 31 2.3.8 Jahia configuration externalization................................................................................................ 40 2.3.9 Portlet deployment ........................................................................................................................ 41

2.4 Weblogic 10 ......................................................................................................................................... 43 2.4.1 Jahia deployment.......................................................................................................................... 43 2.4.2 Jahia configuration externalization................................................................................................ 47

2.5 JBoss 4.2.3 / JBoss 4.3.0..................................................................................................................... 49 2.5.1 Install and configure JBoss ........................................................................................................... 49 2.5.2 Deploy Jahia ................................................................................................................................. 49 2.5.3 Create datasource ........................................................................................................................ 49 2.5.4 User for the UsersRolesLoginModule ........................................................................................... 50

of 91


2.5.5 Move and remove some JARs...................................................................................................... 50 2.5.6 Modify files .................................................................................................................................... 51 2.5.7 Start Jahia..................................................................................................................................... 52

2.6 Database.............................................................................................................................................. 52 2.6.1 MySQL .......................................................................................................................................... 52 2.6.2 PostgreSQL .................................................................................................................................. 52 2.6.3 Oracle ........................................................................................................................................... 53 2.6.4 Microsoft SQL Server.................................................................................................................... 53

2.7 Personalizing URLs.............................................................................................................................. 54 2.7.1 Configuring Jahia's servlet path .................................................................................................... 54 2.7.2 URL Rewriting............................................................................................................................... 55 2.7.3 Changing port number .................................................................................................................. 56

2.8 Caching ................................................................................................................................................ 58 2.8.1 The browser cache layer............................................................................................................... 59 2.8.2 The front-end html cache layer ..................................................................................................... 60 2.8.3 Object caches ............................................................................................................................... 60 2.8.4 Database caches .......................................................................................................................... 60 2.8.5 Jahia.properties file....................................................................................................................... 60 2.8.6 EHCACHE configuration............................................................................................................... 61 2.8.7 Changing the cache provider (for advanced users only) .............................................................. 61

2.9 Configuration File Externalization ........................................................................................................ 61 2.9.1 Feature functional description....................................................................................................... 62 2.9.2 Feature technical description ........................................................................................................ 62 2.9.3 jahia.properties ............................................................................................................................. 62 2.9.4 Spring bean definitions ................................................................................................................. 62 2.9.5 Lisence file .................................................................................................................................... 63 2.9.6 repository.xml................................................................................................................................ 63

2.10 Clustering ......................................................................................................................................... 63 2.10.1 BROWSING nodes ....................................................................................................................... 64 2.10.2 AUTHORING nodes...................................................................................................................... 64 2.10.3 PROCESSING nodes ................................................................................................................... 64 2.10.4 INDEXING nodes.......................................................................................................................... 64 2.10.5 Jackrabbit...................................................................................................................................... 65 2.10.6 Jahia.properties ............................................................................................................................ 66 2.10.7 Indexing configuration................................................................................................................... 66

of 91


2.10.8 Sharing webapps .......................................................................................................................... 67 2.10.9 Sticky sessions ............................................................................................................................. 67 2.10.10 Troubleshooting cluster configuration ....................................................................................... 67

2.11 LDAP ................................................................................................................................................ 67 2.12 Single Sign-On: CAS ........................................................................................................................ 69

2.12.1 Jahia ............................................................................................................................................. 70 2.12.2 Troubleshooting ............................................................................................................................ 71

3 Fine Tuning ................................................................................................................................................. 71 3.1 Tomcat ................................................................................................................................................. 72

3.1.1 bin/catalina.sh ............................................................................................................................... 72 3.1.2 conf/server.xml.............................................................................................................................. 73

3.2 Database.............................................................................................................................................. 73 3.3 Jahia.properties.................................................................................................................................... 74

3.3.1 Output cache expiration ................................................................................................................ 75 3.3.2 Session Duration........................................................................................................................... 75 3.3.3 Development mode....................................................................................................................... 76

4 Monitoring.................................................................................................................................................... 76 4.1 JAMon .................................................................................................................................................. 77

4.1.1 Activating / deactivating monitoring .............................................................................................. 78 4.1.2 Accessing the reporting user interface.......................................................................................... 78 4.1.3 Steps to completely deactivate the service interception. .............................................................. 79

4.2 Monitoring server memory, CPU usage, threads and sessions ........................................................... 79 4.2.1 Monitoring Tomcat and Jahia through LambdaProbe................................................................... 80

4.3 Stack trace dumps ............................................................................................................................... 80 4.3.1 UNIX ............................................................................................................................................. 80 4.3.2 Windows ....................................................................................................................................... 81

4.4 Memory dumps .................................................................................................................................... 81 4.5 Java profilers........................................................................................................................................ 82 4.6 Others Issues ....................................................................................................................................... 82

5 Frequently asked questions (FAQ).............................................................................................................. 83 5.1 How to backup my Jahia? .................................................................................................................... 83 5.2 How to restore an environment from a backup? .................................................................................. 85 5.3 How to upgrade to a newer version? ................................................................................................... 87

5.3.1 Using the upgrade patches ........................................................................................................... 87 5.3.2 Reinstalling your environment and using the XML import feature to recover your content........... 87

of 91


5.4 Modifying the Logging Level ................................................................................................................ 88 5.5 Upgrade the Tomcat Application Server .............................................................................................. 89

of 91


1 Overview 1.1 Introduction Jahia delivers the first Web Content Integration software by combining Enterprise Web Content Management

with Document Management and Portal features.

By leveraging state of the art Open Source frameworks and libraries, Jahia offers a complete solution for

developing, integrating, delivering, and managing content across intranets, extranets, and internets with a

much lower total cost of ownership than proprietary systems.

1.2 What’s in this documentation? This document is intended to give an overview of the various aspects of advanced configuration, installation

and fine tuning of Jahia Enterprise Edition v6.1. It is intended for system administrators and advanced users.

This guide is structured in the following way:

Chapter 2: System requirements and installation of Jahia on various platforms

Chapter 3: Fine tuning your Jahia server

Chapter 4: Monitoring your server for performance

Chapter 5: FAQ

Should you have questions, please do not hesitate to contact us as mentioned on our website

(http://www.jahia.com) or Community website (http://www.jahia.org).

of 91


2 Configuration 2.1 Installation Please find below the minimum system requirements in order to properly run Jahia Enterprise Edition v6.1.

System requirements

OS:

• Windows NT / 2000 / XP • Linux • Solaris • Mac OSX

Suggested Min. Development Configuration:

• Bi-Pro Pentium 2GHz or + • 2 GB RAM • 5 GB HD

Suggested Min. Production Environments:

• Bi-or quadri Pro (64 bits CPU and OS) • 4 or 8 GB RAM • 100 GB HD

Warning: 32 bits JVM are limited in max memory (1.5 GB under Windows - 2 or 3 GB under Linux/Solaris).

Jahia EE v6.1 tries to cache a maximum of data in order to boost performance. So we highly recommend 64

bits environments with enough memory available at least for all production environments.

Java Virtual Machine (JVM)

In order to run Jahia, you first need to install a Java 2 Software Development Kit (JDK or Java2SE SDK) 1.5 as

minimum on your system. As Jahia needs to compile some jsp files, the Java Runtime Environment (or JRE)

will not work, you will need to install the complete JDK (or Java2SE SDK).

You can find both Linux and Windows versions on the SUN web site:

http://java.sun.com/j2se/

of 91


2.2 Preparing your system To check if Java is already installed on your system, type the following command line at the prompt of your

system:

java -version

You should get a message indicating which Java version is installed on your system. Please note that the

same message will be displayed if you only have a JRE installed. If an error is returned, you probably don't

have a complete JDK installed.

If you have installed other versions of the Java Development Kit, Java Runtime Environment or other Java

servers on your system, we recommend that you run a few checks before starting the installation in order to be

sure that Jahia will run without problems.

Check that you have no TOMCAT_HOME and no CATALINA_HOME environment variable set. Note that once installed,

Jahia will check at run time that this variable is not already set, and will stop if it is the case.

To install a Java Virtual Machine on a Windows system (WindowsNT, Windows 2000 or Windows XP), you

need to have administrator rights on your computer. Please contact your system administrator if you don’t have

sufficient permissions.

After the installation, you have to set the JAVA_HOME environment variable to the directory where your have

installed the Java Virtual Machine. The default installation path of the SUN 1.5.0 Java Virtual Machine on

Windows is "c:\j2sdk1.5.0_xx", “xx” is the release number. Note that Jahia will check at run time that this

variable is correctly set, and will stop if it is not the case.

To setup this variable, follow these steps:

2.2.1 Under Windows i) Open the Control Panel, and the System option. Then, depending on your system:

• Select the Advanced tab and click on the Environment Variables button (Windows 2000/XP) • Select the Properties tab and click on the Environment button (Windows NT)

ii) Click on New in the "System variables" part to add a new environment variable. Enter the following

information:

• Variable name: JAVA_HOME • Variable value: c:\j2sdk1.5.0_xx (If you have not installed the Java Virtual Machine in the default

directory, replace this value with the correct path)

of 91


Click on OK to validate your entry. The Java Virtual Machine should now be correctly set-up. Please note that

on Windows NT you will need to restart your computer to apply the changes.

Click on OK to validate your entry. The Java Virtual Machine should now be correctly set-up. Please note that

on Windows NT you will need to restart your computer to apply the changes.

2.2.2 Under Linux Set the JAVA_HOME variable to the root directory of your JDK installation. Both examples below suppose you

have installed the JDK version 1.5 in your /usr/java directory. The classpath is usually set by typing:

export JAVA_HOME=usr/java/j2sdk1.5.0_xx (in bash or ksh)

export JAVA_HOME usr/java/j2sdk1.5.0_xx (in csh or tcsh)

2.2.3 Under Solaris Set the JAVA_HOME variable to the root directory of your JDK installation. The examples below suppose you have

installed the JDK version 1.5 in your /usr/java directory. The classpath is usually set by typing:

export JAVA_HOME=/usr/java (in ksh)

JAVA_HOME=/usr/java;export (in sh)

setenv JAVA_HOME /usr/java (in csh or tcsh)

2.2.4 Default Embedded Java application Server The default Jahia Enterprise Edition v6.1 is distributed with an embedded Apache Tomcat 6.0.18 application

server.

No manual configuration of the server is required, as it will be directly setup during the Jahia installation.

Please note that Jahia Web Content Integration software is configured to run by default on port 8080, and that

it will create a conflict if you have another instance of Tomcat or any other server running on the same port.

2.2.5 Default Embedded Database Jahia Enterprise Edition v6.1 is by default distributed with the HyperSonicSQL database. If you wish to get

started rapidly, you can use the provided HyperSonic database as is. You can of course during the

configuration wizard of Jahia choose to install Jahia to another more robust database.

of 91


2.2.6 Tomcat Jahia presents itself in the form of a tar.gz package in tomcat. Extract the file and then, if under windows,

launch the JahiaInstallation.bat, and follow the installation process. Otherwise just launch the startup.sh from

the bin folder and point your browser to http://localhost:8080/config

The first time you run Jahia, it will open the Jahia configuration wizard to set-up the different parameters

necessary to operate correctly.

A step-by-step guide on how to configure your Jahia follows.

2.2.6.1 Folder structure after installation

We present here a brief structure of the folders in Jahia along with the important files that will be used

throughout this guide.

|-- ./bin | |-- ./bin/catalina.bat | |-- ./bin/catalina.sh | |-- ./bin/shutdown.bat | |-- ./bin/shutdown.sh | |-- ./bin/startup.bat | |-- ./bin/startup.sh |-- ./conf | |-- ./conf/server.xml | |-- ./conf/tomcat-users.xml | `-- ./conf/web.xml |-- ./webapps | |-- ./webapps/config | |-- ./webapps/ROOT | | |-- ./webapps/ROOT/META-INF | | | |-- ./webapps/ROOT/META-INF/context.xml | | |-- ./webapps/ROOT/WEB-INF | | | |-- ./webapps/ROOT/WEB-INF/classes | | | |-- ./webapps/ROOT/WEB-INF/etc | | | | |-- ./webapps/ROOT/WEB-INF/etc/cas | | | | | `-- ./webapps/ROOT/WEB-INF/etc/cas/cas.properties | | | | |-- ./webapps/ROOT/WEB-INF/etc/config | | | | | |-- ./webapps/ROOT/WEB-INF/etc/config/jahia.properties | | | | | `--. /webapps/ROOT/WEB-INF/etc/config/log4j.xml | | | | |-- ./webapps/ROOT/WEB-INF/etc/htmleditors | | | | |-- ./webapps/ROOT/WEB-INF/etc/opensearch | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository | | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository/accesscontrol.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository/exo | | | | | | `-- ./webapps/ROOT/WEB-INF/etc/repository/exo/jahia-nodetypes.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository/jackrabbit | | | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository/jackrabbit/repository.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository/nodetypes | | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository/root.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/repository/rules | | | | |-- ./webapps/ROOT/WEB-INF/etc/services | | | | | `-- ./webapps/ROOT/WEB-INF/etc/services/workflow | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-administration.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-basejahiaconfig.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-compass.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-dao.xml

of 91


| | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-engines.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-hibernate.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-indexationpolicy.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-listeners.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-logsquery.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-manager.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-metadata.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-notification.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-nstep.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-pipelines.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-plutodriver.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-pwdpolicy.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-retentionruledef.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-savesearch.xml | | | | | |-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-services.xml | | | | | `-- ./webapps/ROOT/WEB-INF/etc/spring/applicationcontext-templates.xml | | | | |-- ./webapps/ROOT/WEB-INF/etc/struts | | | | | |-- ./webapps/ROOT/WEB-INF/etc/struts/struts-config.xml | | | | |-- ./webapps/ROOT/WEB-INF/etc/toolbar | | | | `-- ./webapps/ROOT/WEB-INF/etc/xml_dtd | | | |-- ./webapps/ROOT/WEB-INF/fragments | | | |-- ./webapps/ROOT/WEB-INF/lib | | | `-- ./webapps/ROOT/WEB-INF/var | | | |-- ./webapps/ROOT/WEB-INF/var/content | | | | |-- ./webapps/ROOT/WEB-INF/var/content/bigtext | | | | `-- ./webapps/ROOT/WEB-INF/var/content/tmp | | | |-- ./webapps/ROOT/WEB-INF/var/db | | | | `-- ./webapps/ROOT/WEB-INF/var/db/sql | | | | `-- ./webapps/ROOT/WEB-INF/var/db/sql/schema | | | |-- ./webapps/ROOT/WEB-INF/var/dbdata | | | |-- ./webapps/ROOT/WEB-INF/var/field_definitions | | | |-- ./webapps/ROOT/WEB-INF/var/imports | | | |-- ./webapps/ROOT/WEB-INF/var/patches | | | | |-- ./webapps/ROOT/WEB-INF/var/patches/groovy | | | |-- ./webapps/ROOT/WEB-INF/var/prepackagedSites | | | |-- ./webapps/ROOT/WEB-INF/var/repository | | | | `-- ./webapps/ROOT/WEB-INF/var/repository/workspaces | | | |-- ./webapps/ROOT/WEB-INF/var/scripts | | | |-- ./webapps/ROOT/WEB-INF/var/search_indexes | | | | |-- ./webapps/ROOT/WEB-INF/var/search_indexes/MySite | | | |-- ./webapps/ROOT/WEB-INF/var/shared_templates | | | `-- ./webapps/ROOT/WEB-INF/var/tmp | | |-- ./webapps/ROOT/admin | | |-- ./webapps/ROOT/configuration_wizard | | |-- ./webapps/ROOT/css | | |-- ./webapps/ROOT/engines | | |-- ./webapps/ROOT/errors | | |-- ./webapps/ROOT/events | | |-- ./webapps/ROOT/gwt | | |-- ./webapps/ROOT/html | | |-- ./webapps/ROOT/htmleditors | | | |-- ./webapps/ROOT/htmleditors/fckeditor | | | `-- ./webapps/ROOT/htmleditors/simpletext | | |-- ./webapps/ROOT/iphone | | |-- ./webapps/ROOT/javascript | | |-- ./webapps/ROOT/monitor | | |-- ./webapps/ROOT/processing | | |-- ./webapps/ROOT/templates | | | |-- ./webapps/ROOT/templates/core_templates | | | |-- ./webapps/ROOT/templates/social-templates | | | |-- ./webapps/ROOT/templates/test_templates | | | `-- ./webapps/ROOT/templates/web_templates | | |-- ./webapps/ROOT/tools | | |-- ./webapps/ROOT/views `-- ./work

of 91


We give here a brief overview of the important folders:

webapps/ROOT/engines: This directory contains all the jsp files of the engines of Jahia (the popup windows).

webapps/ROOT/htmleditors: You will find here all files necessary to run a given HTML editor inside Jahia.

Default editors include the FCKEditor and the Simple Text.

webapps/ROOT/templates : Templates deployed on your server (shared among all virtual sites).

webapps/ROOT/META-INF/context.xml: Database connection information.

webapps/ROOT/WEB-INF/classes: Resource bundle files used to translate the Jahia interface in other

languages are stored in this directory. There is normally at least 3 files for each language,

JahiaAdministrationResources.properties, JahiaEnginesResources.properties and

JahiaMessageResources.properties.

webapps/ROOT/WEB-INF/etc : The etc directory contains most of the configuration files of Jahia. Config sub-

directory contains the main configuration file, jahia.properties, and the error logging log4j.xml. Htmleditors

contains the file to configure some settings for the various html editors installed. It also contains the

configuration files for jackrabbit repository.

webapps/ROOT/WEB-INF/var/content: Information not stored inside the database will be saved here.

webapps/ROOT/WEB-INF/var/db The database scripts to create the db schema of Jahia and to connect to

the corresponding database can be found here.

webapps/ROOT/WEB-INF/var/search_indexes : When the search engine indexes your site, the search index

will be stored in this directory. When you create a new virtual site, it will be automatically indexed.

webapps/ROOT/WEB-INF/var/shared_templates: Templates set in that directory will be available for selec-

tion in the drop down list when you create a new virtual site.

work: This directory will contain a compiled (for instance simple_jsp.class) and a readable version (for instance

simple_jsp.java) of your templates, or the templates of Jahia engines if you don’t use the precompiled engines

files. This can prove helpful in case you have an error in a template showing in the tomcat logs, for instance:

sitemap_jsp.java:984: illegal start of expression. If you want to make sure that all jsp files of the

templates are recompiled after a change, you may want to delete the Standalone directory in Work. Next time

you access a page, Tomcat will recompile all jsp files used by the page.

of 91


2.2.6.2 Jahia configuration externalization (available since jahia 6.1.1.3 (r37857) )

This section focuses on how to deploy the externalized configuration in Tomcat, and how to reference it by the

deployed Jahia application. For more information about the externalized configuration itself, please refer to the

dedicated section.

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. Add the externalized folder to the TOMCAT classpath: in the <Tomcat>/bin/setclasspath.sh file, add the

custom folder to the classpath variable: CLASSPATH=$CLASSPATH:<My externalized folder>

(CLASSPATH=$CLASSPATH:/app/jahia/externalizedConf for example)

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

5. In order to externalize the license file, in the <Tomcat>/bin/catalina.sh file, set the license Java system

property with the full path to your license file. Set this property by adding it to the CATALINA_OPTS

variable:

(CATALINA_OPTS="$CATALINA_OPTS –Xms4096m –Xmx4096m -Djava.awt.headless=true -

XX:MaxPermSize=192m -server -Dhibernate.jdbc.use_streams_for_binary=true -verbose:gc -

Djahia.license=/app/jahia/externalizedConf/license-pro-test.xml for example)

2.3 Websphere Application Server 6.1.x

2.3.1 Supported platforms The following procedure has only been tested with version 6.1.0.29 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 on the platform. Make sure to read the release notes of any update packs that are

installed on the server to adjust this procedure accordingly. The IBM Websphere Application Server platform is

very sensitive to service pack changes, so make sure you are running at least the version indicated above.

Please also note that all the screenshots were taken with version 6.1.0.29, and that IBM has a tendency to

modify the user interface quite often, so you might have to adjust to changes if trying to deploy with another

version (not recommended of course ).

of 91


2.3.2 Known issues We are working on solving some issues that are very specific to this platform, which usually evolves a little

slower than more bleeding edge servers.

The TestServlet unit testing servlet does not work (http://jira.jahia.org/browse/QA-98)

The jahia URL rewriting doesn’t work neither ((http://jira.jahia.org/browse/QA-483) so you need to disable this

feature in jahia until this bug is resolved. For deactivating the feature please refer to the section “2.7.2 URL

Rewriting”.

2.3.3 Configuring Jahia 2.3.3.1 Installing from package

1. Download the jahia/tomcat package

2. Start the server, run the configuration wizard, selecting the database you will use with your Websphere

server

3. Shutdown the server

2.3.3.2 Installing from source code [Developers only]

You have also the possibility to build the Jahia application already configured. This is not recommended for

production environments, but it can let you save time during development process.

1. Before compiling Jahia, you must configure the USER_HOME/.m2/settings.xml file to have the following

configuration. Make sure the “configure” profile points to the database you will be using with your

Websphere server. In the following example we have set it up with an Oracle database :

<profile> <id>configure</id> <properties> <jahia.configure.active>true</jahia.configure.active> <jahia.configure.databaseType>oracle</jahia.configure.databaseType> <jahia.configure.databaseUrl>jdbc:oracle:thin:@ORACLE_SERVER_IP_ADDRESS:1521:test</jahia.configure.databaseUrl> <jahia.configure.databaseUsername>username</jahia.configure.databaseUsername> <jahia.configure.databasePassword>password</jahia.configure.databasePassword> <jahia.configure.localIp>jahia_server_ip_address</jahia.configure.localIp> <jahia.deploy.processingServer>true</jahia.deploy.processingServer> </properties> </profile>

of 91


Making sure you replace the ORACLE_SERVER_IP_ADDRESS marker with the IP address of your Oracle

server.

2. To prepare for deployment, we will first deploy into Tomcat, make some modifications to the

configuration, and then generate a WAR file we can then deploy on Websphere. So in the settings.xml

file make sure you are using a profile for Tomcat like the following :

<profile>  <id>andromeda-deployment-tomcat6-dev</id> <properties> <jahia.deploy.targetServerType>tomcat</jahia.deploy.targetServerType> <jahia.deploy.targetServerVersion>6</jahia.deploy.targetServerVersion> <jahia.deploy.targetServerDirectory>/Users/loom/java/deployments/jahia-andromeda/apache-tomcat-6.0.18</jahia.deploy.targetServerDirectory> <jahia.deploy.war.dirName>jahia</jahia.deploy.war.dirName> <jahia.deploy.war.contextPath>/jahia</jahia.deploy.war.contextPath> <jahia.deploy.war.servletPath>/Jahia</jahia.deploy.war.servletPath> <jahia.debug.address>socket:hostname=localhost,port=8000</jahia.debug.address> </properties> </profile>

3. The active profiles still in the settings.xml file should then look like this :

<activeProfiles> <activeProfile>gwt-1.5.3</activeProfile> <activeProfile>configure</activeProfile> <activeProfile>andromeda-deployment-tomcat6-prod</activeProfile> </activeProfiles>  <pluginGroups> <pluginGroup>org.jahia.server</pluginGroup> <pluginGroup>org.apache.pluto</pluginGroup> <pluginGroup>com.atlassian.maven.plugins</pluginGroup> </pluginGroups>

4. Once this is all setup, simply launch the build, deploy & configure process with the following command

line:

mvn clean install jahia:deploy jahia:configure

5. Please continue on to the next section “Packaging for Websphere”

2.3.4 Packaging for Websphere 1. We assume you have either completed the installation from source code or from package previously

described

of 91


2. Choose one of the two following options (2A or 2B)

2A Copy the following libs from tomcat/lib/ to the Websphere/ApplicationServer/lib/ext/ directory. Please note

that the jaxb-api-2.1.jar comes from tomcat/endorsed/ instead of tomcat/lib/

2B Copy those libraries in the folder of your choice, 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. 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).

activation-1.1.jar castor-1.1.1.jar ccpp-1.0.jar commons-logging-1.1.1.jar jaxb-api-2.1.jar jaxb-impl-2.1.7.jar log4j-1.2.15.jar pluto-container-2.0.0-RI-jahia.jar pluto-descriptor-api-2.0.0-RI.jar pluto-descriptor-impl-2.0.0-RI.jar pluto-taglib-2.0.0-RI.jar portals-bridges-common-1.0.4.jar stax-1.2.0.jar stax-api-1.0.1.jar xercesImpl-2.9.1.jar xmlParserAPIs-2.9.1.jar

3. Copy the portlet-api-2.0.jar from tomcat/libs to WebSphere/java/jre/lib/ext/

4. In the tomcat/webapps/ROOT/WEB-INF/web.xml file, you must comment the following lines (depending

on the version of Jahia you are deploying, those lines may be already commented):

<servlet> <servlet-name>Test</servlet-name> <servlet-class>org.jahia.bin.TestServlet</servlet-class> <load-on-startup>99</load-on-startup> </servlet>

5. And also the lines :

<servlet-mapping> <servlet-name>Test</servlet-name> <url-pattern>/test/*</url-pattern> </servlet-mapping>

6. And finally uncomment the following lines :

<!--

of 91


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

7. In the tomcat/webapps/ROOT/WEB-INF/etc/repository/jackrabbit/repository.xml and

tomcat/webapps/ROOT/WEB-INF/var/repository/workspaces/default/workspace.xml, replace all

instances of

<param name="driver" value="javax.naming.InitialContext" /> <param name="schema" value="@SCHEMA@" /> <param name="url" value="java:comp/env/jdbc/jahia" />

with :

<param name="driver" value="oracle.jdbc.OracleDriver" /> <param name="schema" value="oracle" /> <param name="url" value="jdbc:oracle:thin:@ORACLE_SERVER_IP_ADDRESS:1521:test" /> <param name="user" value="username" /> <param name="password" value="password" />

Making sure you replace the ORACLE_SERVER_IP_ADDRESS marker with the IP address of your Oracle

server.

[Developers only] : If you have installed Jahia from source code, you only need to configure the repository.xml

file, as the workspace.xml does not yet exists and will be generated at first startup, based on your reconfigured

repository.xml file.

8. In the tomcat/webapps/ROOT/WEB-INF/etc/config/quartz.properties file, uncomment the following lines

#org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreCMT #org.quartz.jobStore.nonManagedTXDataSource = jahiaNonTxDS #org.quartz.jobStore.dontSetAutoCommitFalse = true

and comment the following line:

org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreTX

also uncomment this line:

#org.quartz.dataSource.jahiaNonTxDS.jndiURL = java:comp/env/jdbc/jahiaNonTx

9. In tomcat/webaps/ROOT/WEB-INF/etc/config/jahia.properties file change:

server = tomcat

To

of 91


server = was

You need to change the default port 8080 used, to map to the default Websphere port (9080)

o In the /WEB-INF/etc/config/jahia.properties file,

# uncomment the following line and update with the port of the application server #localAccessUri = http\://localhost\:8080 # and update the port to match yours # Ip address of the server on the local network, do not use localhost or 127.0.0.1 here, and make sure it is accessible from parallel servers (such as cluster nodes) localIp = 10.8.37.157 # update the port to match yours (automatically done if you run install wizard after having changed the port at application server level) jahiaWebAppsDeployerBaseURL = http\://localhost\:8080/manager"

o In the /WEB-INF/etc/spring/applicationcontext-services.xml file, update the port used here :

<bean id="FileListSync" class="org.jahia.services.deamons.filewatcher.FileListSync" factory-method="getInstance"> [...] <property name="syncUrl"> <value>http://${localIp}:8080</value> </property>[...] </bean>

10. Delete the following file: WEB-INF/ibm-web-bnd.xmi

11. You can now launch the following command from the tomcat/webapps/ROOT directory:

jar cvf jahia.war .

This will build the WAR file ready for deployment in Websphere. But first we must configure the Datasource

that need to be available before we can deploy the WAR in the server, as well as perform a configuration about

filters.

2.3.5 Websphere Filter configuration WebSphere 6.1.0.5 and above checks if a URL is mapped to a servlet or a file before it puts a request through

the filter chain. As we do not have a servlet or a file that is mapped to a URL:

http:///a/AZ/

of 91


WebSphere 6.1.0.5 sends a 404 to the user before giving the UrlRewrite filter a chance to redirect a URL to the

correct place.

To make the filter invoke on a request without a servlet mapping you should be able to do the following in the

WebSphere Admin Console:

• Expand Servers -> Application Servers -> <server> -> Web Container Settings and click on the “Web

container” link

• Then click on the “Custom Properties” link

of 91


• You should see this screen:

• 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:

• Save the update and restart the server (click on “Save” on the following screen and then use the

stopServer/startServer scripts to restart the server).

2.3.6 Data sources definition You need to define two data sources in your Application server. Those data sources will be further mapped on

the resources declared in your Jahia application.

of 91


2.3.6.1 JDBC Provider creation

You need to create a JDBC provider to define connection with 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 go directly to next

paragraph.

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

• Copy the connector jar file if required in a local directory. (You can put it in the lib/ directory of your

application server to reuse the already defined WAS_LIBS_DIR Websphere environment variable) For

Oracle, use the following driver: ojdbc5-11.1.0.7.0.jar and ora18n-11.1.0.7.0 in Websphere

configuration and not the ojdbc14.jar one. You can find the Oracle driver JARs in Jahia’s WEB-INF/lib

directory

• In Environment -> Websphere Variables, check if a variable named ORACLE_JDBC_DRIVER_PATH is

defined and if it is pointing to directory where you copied the driver JARs you have deployed in the

previous step. If it is not, you can edit the ORACLE_JDBC_DRIVER_PATH to point to the

WAS_LIBS_DIR directory like illustrated below :

of 91


When clicking OK, make sure you then apply the change to the master configuration :

• Open Resources / JDBC / JDBC Providers, specify Server scope (Node=node_name,

Server=server_name)

• Click on “New” button

of 91


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

• In the next screen, fill in as below:

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

of 91


• 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 more recent version of the driver:

• You should now be on the following screen :

of 91


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

${ORACLE_JDBC_DRIVER_PATH}/ojdbc5-11.1.0.7.0.jar

${ORACLE_JDBC_DRIVER_PATH}/ora18n-11.1.0.7.0.jar

• Click “OK”

of 91


• On this screen:

Click “Save” (the warning is ok, we have setup everything properly at this point)

2.3.6.2 Data sources creation

2.3.6.2.1 Authentication alias creation

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

• Open Resources / JDBC / Data sources

• Specify Server scope

• Click on “New” then click on the blue link “Create an new J2C authentication”

of 91


• On this screen :

Click on “New”

• Fill in all required fields on screen, entering your database user and password information :

• Click on Apply / Save

• On this screen

Click “Save”

2.3.6.2.2 Data sources creation

You can now create your Data sources. The Jahia application requires two Data sources: one with JNDI name jdbc/jahia and one with JNDI name jdbc/jahiaNonTx.

of 91


• Open Resources / JDBC / Data sources

• Specify Server scope

• Click on New

• Specify an explicit name for your Data source, specify one of the required JNDI names, and select your

previously defined authentication alias:

• Click on Next

• Select the JDBC Provider you want to use :

• Click on Next

of 91


• 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

• Your summary screen should look like this:

If everything looks ok, click on “Finish”, otherwise use the “Previous” button to perform the necessary

changes.

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

of 91


• 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.

• Redo the same operation for a second DataSource with the same settings, and make sure you give it

the JNDI name: jdbc/jahiaNonTx . Here is the summary screen for the second Datasource:

of 91


• When using Oracle, for each Datasource, go back into the Datasource, select “Custom properties” and

make sure the following property is set to blank (no value) : oracle9iLogTraceLevel

2.3.7 Deploying in Websphere You are now ready to deploy Jahia into Websphere. Here are the steps to achieve this:

1. Remove the default application from the server, as it will interfere with Jahia that will also use the

default (root) context. To do so go into Applications->Enterprise Applications, select the default

application and click “Uninstall”. You should see the following screen:

Click “OK” and once the operation has completed, save the configuration to the master configuration.

of 91


2. Deploy using the Applications->New Application screen. Upload the jahia.war file, or copy it to the disk

of the Websphere Server and use the remote file system selection to point to it.

3. In the Context root input box, enter “/”

4. Click “Next”

of 91


5. Leave all the defaults on the screen below and click “Next”

of 91


6. On the “Map modules” to server screen, simply click Next:

7. On the resource screen, make sure you use the Container authentication you setup previously and

connected it to both the jdbc/jahia and jdbc/jahiaNonTx datasources. First under “Use default method”

make sure you select your newly created authentication alias.

8. Then, select both resource reference and click the “Apply” button

of 91


9. Then for each resource reference click the “Browse” button and associate it to the correct datasource

like in the below example for the jdbc/jahia resource:

of 91


10. Your screen should look like this (check the authentication method in the resources is properly set)

11. Click “Next”

of 91


12. On the “Map virtual hosts to web modules” screen, simply leave the default and click “Next”:

13. On the “Map context roots for Web modules” screen, simply leave the defaults and click “Next”:

of 91


14. On the “Summary” screen click “Finish”

15. Websphere will now deploy the application, which can take some time. Once it is completed, click

“Save” to save to the master configuration

of 91


16. If you have declared you shared libs as a Websphere Shared Library (see 2.3.4 step 2B), your Jahia

application has to reference this library. If you have not performed this during the deployment, open

“Applications” / “Enterprise applications” / “Jahia” / “Shared library references” and map your shared

library on the Jahia application (not the Jahia module).

17. You should then be able to go to the Enterprise Application screen and start the jahia_war application

by selecting it and clicking the “Start” button. Check the logs for proper startup (the logs are located in

IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1/SystemOut.log)

18. Then connect to Jahia using the url: http://websphere_server_ipaddress:9080 and you should see the

Jahia login screen. Create a new site, validate the home page and you should be all set.

of 91


2.3.8 Jahia configuration externalization (available since jahia 6.1.1.3 (r37857) ) 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 dedicated section.

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

7. Create in this folder the following subfolders structure: org/jahia/config/ (to have

/app/jahia/externalizedConf/org/jahia/config/ )

8. 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)

9. Open “Applications” / “Enterprise applications” / “Jahia” / “Shared library references” and map your

shared library on the Jahia module (not the Jahia application).

10. 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.

of 91


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

2. 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. Your web.xml should reference it as in the example below :

<taglib> <taglib-uri>http://java.sun.com/portlet_2_0</taglib-uri> <taglib-location>/tld/std-portlet_2_0.tld</taglib-location> </taglib>

3. Click on “Enterprise Application”

4. Check jahia_war and click on update button

of 91


5. Select “Replace or add single module”, select your *.war file and specify the context root with the same

name as the WAR (but without the WAR extension). In the following screenshot, portlet-testsuite is

used as an example. Make sure you also enter the path for the value “Specify the path beginning…”

6. Click the “Next” buttons until the last step

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

8. 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.

of 91


2.4 Weblogic 10 2.4.1 Jahia deployment

• Download the jahia/tomcat package

• Start tomcat, play the configuration wizard, select the same database type as the one you will use on your weblogic server

• Create a new weblogic domain if nested (see Configuration wizard of Weblogic)

• Copy the following libraries from tomcat/lib to your weblogic domain lib directory:

activation-1.1.jar castor-1.1.1.jar ccpp-1.0.jar commons-logging-1.1.1.jar jaxb-impl-2.1.7.jar log4j-1.2.15.jar pluto-container-2.0.0-RI-jahia.jar pluto-descriptor-api-2.0.0-RI.jar pluto-descriptor-impl-2.0.0-RI.jar pluto-taglib-2.0.0-RI.jar portlet-api-2.0.jar stax-1.2.0.jar stax-api-1.0.1.jar xercesImpl-2.9.1.jar xmlParserAPIs-2.9.1.jar

• Copy the following library from tomcat/endorsed to your weblogic domain lib directory :

jaxb-api-2.1.jar

• Create a directory to deploy your Jahia application (let’s call it jahia.ear for example)

• Inside jahia.ear create a directory META-INF

• In META-INF create a file named application.xml, containing:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" "http://java.sun.com/dtd/application_1_3.dtd"> <application> <display-name>Jahia EE</display-name> <description>Jahia Full Package</description> <module> <web> <web-uri>jahia.war</web-uri> <context-root>/</context-root> </web> </module>

of 91


</application>

Note: in this example, we suppose that the context is ROOT

• Create another file called weblogic-application.xml, containing:

<?xml version="1.0"?> <weblogic-application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.bea.com/ns/weblogic/90" xsi:schemaLocation="http://www.bea.com/ns/weblogic/90 http://www.bea.com/ns/weblogic/90/weblogic-application.xsd http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/j2ee_1_4.xsd "> <xml> <parser-factory> <saxparser-factory> org.apache.xerces.jaxp.SAXParserFactoryImpl </saxparser-factory> <document-builder-factory> org.apache.xerces.jaxp.DocumentBuilderFactoryImpl </document-builder-factory> <transformer-factory> org.apache.xalan.processor.TransformerFactoryImpl </transformer-factory> </parser-factory> </xml> <prefer-application-packages> <package-name>antlr.*</package-name> </prefer-application-packages> </weblogic-application>

• Copy the Jahia webapp from tomcat into jahia.ear (if your tomcat webapp is called ROOT, then copy

the content of ROOT/ inside a directory named jahia.war in jahia.ear). The name of the folder inside

which you copy the webapp (here jahia.war) has to fit the web-uri parameter of the module defined in

application.xml

• Move some libs from jahia.war/WEB-INF/lib into jahia.ear/:

jms-1.1.jar jta-1.0.1B.jar mail-1.4.jar xalan-2.7.0.jar

• In the /WEB-INF/web.xml file, you must comment the following lines (these lines may be already

commented, depending on the version of Jahia 6.1 you are using):

<servlet> <servlet-name>Test</servlet-name> <servlet-class>org.jahia.bin.TestServlet</servlet-class>

of 91


<load-on-startup>99</load-on-startup> </servlet>

• And also the lines lines (these lines may be already commented, depending on the version of Jahia 6.1

you are using):

<servlet-mapping> <servlet-name>Test</servlet-name> <url-pattern>/test/*</url-pattern> </servlet-mapping>

• You need to change the default port 8080 used when installing Tomcat

o In the /WEB-INF/etc/config/jahia.properties file,

uncomment "#localAccessUri = http\://localhost\:8080" and update the port to match yours "jahiaWebAppsDeployerBaseURL = http\://localhost\:8080/manager" : update the port to match yours (automatically done if you run install wizard after having changed the port at application server level)

o In the /WEB-INF/etc/spring/applicationcontext-services.xml file,

update used port here: <bean id="FileListSync" class="org.jahia.services.deamons.filewatcher.FileListSync" factory-method="getInstance"> [...] <property name="syncUrl"> <value>http://${localIp}:8080</value> </property>[...] </bean>

• If you use Oracle as database server, configure Qwartz to use WebLogicOracleDelegate instead of the

generic OracleDelagate

o In WEB-INF/etc/config/quartz.properties

org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.oracle.weblogic.WebLogicOracleDelegate

• Start your weblogic domain

• Create your datasource (with jndi name = jdbc/jahia) add your domain server as a target

of 91


• Go to “Deployment” section of your weblogic domain and deploy your Jahia application by selecting

your jahia.ear folder as application path

of 91


• Access the Jahia application (http://localhost:7001/)

• Create a virtual site

• Go to http://localhost:7001/tags.jsp

• Due to some bug in weblogic when parsing DateHeader from a request you might have to change you

startup script to ensure you are in locale en_US for the server virtual machine :

add « -Duser.language=en -Duser.country=US » to your JAVA_OPTIONS

2.4.2 Jahia configuration externalization (available since jahia 6.1.1.3 (r37857) ) This section focuses on how to deploy the externalized configuration in WebLogic, and how to reference it by

the deployed Jahia application. For more information about the externalized configuration itself, please refer to

the dedicated section.

1. Create the below folder structure

externalizedConf | |______ META-INF | |______ MANIFEST.MF | |______ org |____ jahia |____ config

2. In MANIFEST.MF put the following content:

of 91


Manifest-Version: 1.0 Class-Path: Extension-Name: jahiaExtConf Specification-Version: 1.0 Implementation-Version: 1.0

3. Put your externalized configurations inside the config/ folder

4. From the externalizedConf folder, package your configurations as a jar file

jar cvfM extConf.jar org META-INF

Do not forget the “M” option so that your manifest is used, instead of generating a new one

5. Go to “Deployment” section of your WebLogic domain and deploy your externalized configurations by

selecting your extConf.jar file

6. Edit jahia.war/META-INF/MANIFEST.MF and add the following lines:

Extension-List: externalizedConf externalizedConf-Extension-Name: jahiaExtConf externalizedConf-Specification-Version: 1.0 externalizedConf-Implementation-Version: 1.0

Add those lines immediately after the last non empty line, without leaving any empty line, otherwise the Jahia

application will no more be able to start.

Your externalized configuration jar is an “Optional Package”. Please refer to the WebLogic documentation if

you need some additional information.

http://download.oracle.com/docs/cd/E17904_01/web.1111/e13706/libraries.htm

of 91


2.5 JBoss 4.2.3 / JBoss 4.3.0 2.5.1 Install and configure JBoss Download and unzip your JBoss package into the desired target location. The installation procedure below

assumes the <JBOSS_HOME> being the root folder of your JBoss server (it contains bin/, server/ and other

folders) and <JBOSS_SERVER_CONFIG> being the folder with your server configuration file set (usually,

<JBOSS_HOME>/server/default for JBoss 4.2.3 and <JBOSS_HOME>/server/production for JBoss 4.3.0).

Edit the <JBOSS_HOME>/bin/run.conf or <JBOSS_HOME>/bin/run.bat (on Windows) and adjust the JVM memory

parameters in the JAVA_OPTS to have (for JBoss 4.3.0 there could be alternatively

<JBOSS_HOME>/bin/run.conf.bat and also files <JBOSS_SERVER_CONFIG>/run.conf and

<JBOSS_SERVER_CONFIG>/run.conf.bat):

-Xms1024m -Xmx1024m -XX:PermSize=256m

In the same file also add the following settings to the JAVA_OPTS environment variable:

-Dorg.jboss.logging.Log4jService.catchSystemOut=false -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp -verbose:gc -Dhibernate.jdbc.use_streams_for_binary=true -Djava.awt.headless=true

In case you run into JMX problems, you could also add this to JAVA_OPTS:

-Djboss.platform.mbeanserver

2.5.2 Deploy Jahia Download Jahia/Tomcat package

Start Tomcat and play the wizard. Select the same database type as the one you will use on your JBoss server.

Copy the Jahia webapp folder (webapps/ROOT) from Tomcat to <JBOSS_SERVER_CONFIG>/deploy/ROOT.war on

JBoss. To avoid conflicts with default JBoss’ ROOT Web application, rename the folder

<JBOSS_SERVER_CONFIG>/deploy/jboss-web.deployer/ROOT.war to e.g. jboss.war

2.5.3 Create datasource a) Create a jahia-ds.xml file in <JBOSS_SERVER_CONFIG>/deploy folder. The content of this file is dedicated

to your database configuration. You will find a lot of examples in the following directory of your JBoss

installation root folder: jboss/docs/examples/jca

of 91


Take one sample file (ie postgres-ds.xml for postgres database), and modify the content of the file with

your database connection data.

In this file replace local-tx-datasource with no-tx-datasource.

Replace the jndi-name with the following:

<jndi-name>jahiaDS</jndi-name>

Enter a valid connection URL to a Jahia database, previously created with the configuration wizard.

Update the system username/password (e.g. jahia/jahia).

b) Go to the <JBOSS_SERVER_CONFIG>/deploy/ROOT.war/WEB-INF/lib and move the corresponding database

driver JAR for your database to <JBOSS_SERVER_CONFIG>/lib.

Note, please, that in order to use HSQL DBMS with Jahia on JBoss, you need to switch the

<JBOSS_SERVER_CONFIG>/deploy/hsqldb-ds.xml configuration from in-process to server mode.

2.5.4 User for the UsersRolesLoginModule Jahia requires a user with the manager and jahiaManager roles for accessing several internal monitoring and

management tools.

a) Add the following user into your file <JBOSS_SERVER_CONFIG>/conf/users.properties (if the file does not

exist, create it):

Jahia=password

(please, change the default password).

b) Add the following role mapping for the user Jahia into your file

<JBOSS_SERVER_CONFIG>/conf/roles.properties (if the file does not exist, create it):

Jahia=manager,jahiaManager

2.5.5 Move and remove some JARs Copy the following JARs from tomcat/lib to the <JBOSS_SERVER_CONFIG>/lib directory on JBoss, removing

existing versions of corresponding JARs (in JBoss those JAR files have no version, e.g. activation.jar, log4j.jar

etc.):

activation-1.1.jar castor-1.1.1.jar ccpp-1.0.jar

of 91


commons-logging-1.1.1.jar log4j-1.2.15.jar pluto-container-2.0.0-RI-jahia.jar pluto-descriptor-api-2.0.0-RI.jar pluto-descriptor-impl-2.0.0-RI.jar pluto-taglib-2.0.0-RI.jar portals-bridges-common-1.0.4.jar portlet-api-2.0.jar stax-1.2.0.jar stax-api-1.0.1.jar xercesImpl-2.9.1.jar xmlParserAPIs-2.9.1.jar

Copy the following JAR from tomcat/lib to the <JBOSS_HOME>/lib/ directory on JBoss, removing existing jaxb-

impl.jar file:

jaxb-impl-2.1.7.jar

Copy the following JAR from tomcat/endorsed to the <JBOSS_HOME>/lib/ and <JBOSS_HOME>/lib/endorsed

directories on JBoss, removing existing jaxb-api.jar files:

jaxb-api-2.1.jar

In <JBOSS_SERVER_CONFIG>/deploy/ROOT.war/WEB-INF/lib remove all jboss*.jar and trove*.jar files and also

the jstl*.jar and standard*.jar. These files will be taken from your JBoss version.

Ensure that <JBOSS_HOME>/lib/endorsed/ has the xalan.jar and xercesImpl.jar inside.

Remove the JAR file <JBOSS_SERVER_CONFIG>/ROOT.war/WEB-INF/lib/derby-10.4.2.0.jar. An issue was

discovered in this version of embedded Derby on JBoss (see https://issues.apache.org/jira/browse/DERBY-

3887).

2.5.6 Modify files Set the server parameter to JBoss and adjust the serverHomeDiskPath parameter in

<JBOSS_SERVER_CONFIG>/ROOT.war/WEB-INF/etc/config/jahia.properties to have the absolute path to the

<JBOSS_SERVER_CONFIG> folder, for example:

server = JBoss serverHomeDiskPath = /opt/jboss-4.2.3.GA/server/default/

of 91


Add the portlet.tld lookup path into <JBOSS_SERVER_CONFIG>/deploy/jboss-web.deployer/conf/web.xml as an

init-param for the jsp servlet:

<servlet> <servlet-name>jsp</servlet-name> ... <init-param> <description>Portlet taglibs</description> <param-name>tagLibJar2</param-name> <param-value>../../lib/pluto-taglib-2.0.0-RI.jar</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet>

2.5.7 Start Jahia Finally, start your JBoss. Call the Jahia URL from your browser (http://localhost:8080/) and create a virtual site

2.6 Database Jahia is by default distributed with the HyperSonicSQL database. If you wish to get started rapidly or for

development purposes, you can use the provided HyperSonic database as is.

Your database should be UTF-8 compliant! Have this in mind when creating a new database for Jahia

Default settings are currently already predefined to allow Jahia to run on HyperSonic, PostgreSQL, MySQL,

Microsoft SQL Server and Oracle. The database configuration options are located under

webapp/ROOT/MET-INF/context.xml

2.6.1 MySQL The default database URL (the connection string) for MySQL is:

jdbc:mysql://localhost/jahia?useUnicode=true&characterEncoding=UTF-8

where localhost should be replaced by the fully qualified domain name (mysql.mydomain.com) or IP address

of the MySQL server if it is not located on the same machine as the Jahia server, and jahia is the default name

of the database where Jahia tables will be created.

If your MySQL server is not running on the standard port (3306), you should add :port after the database name

where port is the port number

2.6.2 PostgreSQL The default database URL (the connection string) for PostgreSQL 8.3 is:

jdbc:postgresql:jahia

of 91


where Jahia is the default name of the database where Jahia tables will be created. If your PostgreSQL server

is located on a distant computer and/or on a non-default port (5432), the database URL should be:

jdbc:postgresql://host:port/database

Make sure your postgreSQL server is accepting TCP connections.

Please refer to your database documentation for detailed instructions on how to configure postgreSQL to

accept TCP connections.

2.6.3 Oracle Jahia also comes with JDBC drivers for Oracle. This drivers works with Oracle 10g,11g.

The default database URL (the connection string) for Oracle is:

jdbc:oracle:thin:@localhost:1521:jahia

where localhost should be replaced by the fully qualified domain name (sqlserver.mydomain.com) or IP

address of the MS SQL Server if it is not located on the same machine as the Jahia server, and Jahia is the

default name of the database where Jahia tables will be created.

1521 is the standard port for Oracle. If you Oracle server is running on a different port, please change it here.

2.6.4 Microsoft SQL Server Jahia is provided with jdbc drivers for MS SQL 2008.

The default database URL (the connection string) for Microsoft SQL Server is:

jdbc:jtds:sqlserver://localhost/jahia

where localhost should be replaced by the fully qualified domain name (sqlserver.mydomain.com) or IP

address of the MS SQL Server if it is not located on the same machine as the Jahia server, and Jahia is the

default name of the database where jahia tables will be created.

If your MS SQL Server is not running on the standard port (3306), you should add :port after the database

address where port is the port number.

jdbc:jtds:sqlserver://localhost:port/jahia

of 91


2.7 Personalizing URLs 2.7.1 Configuring Jahia's servlet path The following section explains how to change the default /cms mapping to a custom servlet path.

In this document we assume that:

• SERVLET_NAME will be your new servlet name (by default it is “cms”). • That you have already installed Jahia previously, and will modify this configuration from an existing

setup.

You should avoid using search and replace as you need to be careful with these modifications. In each of the

following files,

webapps/ROOT/WEB-INF/web.xml

<context-param> <description> </description> <param-name>defaultJahiaServletPath</param-name> <param-value>SERVLET_NAME</param-value> </context-param>  <param-value>(.*/SERVLET_NAME (/.*)?|.*\.jsp(\?.*)?|.*/gwt/.*\.nocache\..*)</param-value> <filter-mapping> <filter-name>ResponseCacheControlFilter</filter-name> <url-pattern>SERVLET_NAME</url-pattern> </filter-mapping> <filter-mapping> <filter-name>ResponseCacheControlFilter</filter-name> <url-pattern>SERVLET_NAME/*</url-pattern> </filter-mapping> <servlet-mapping> <servlet-name>Jahia</servlet-name> <url-pattern>SERVLET_NAME/*</url-pattern> </servlet-mapping>

WEB-INF/etc/struts/struts-config.xml

<forward name="coreEngine" path="/SERVLET_NAME"/> <action path="/SERVLET_NAME" type="org.jahia.bin.JahiaAction" scope="request" unknown="true"> </action

of 91


2.7.2 URL Rewriting As an alternative to performing URL rewriting using the Apache Web Server with the mod_rewrite and

mod_proxy plugins, we present here a method using a J2EE-compatible web filter that is integrated with Jahia

by default and shipped by default with Jahia EE v6.1. For a complete user guide on how to use rules, we

suggest you go their web page.

You might ask why we should configure URL rewriting at the application server level rather than using an

Apache front-end web server? Apart from the added flexibility (the filter event supports custom rules

implemented in Java), using an Apache front-end server adds an extra indirection processing, through the

mod_jk layer. While this has the advantage of adding load-balancing, it also has the disadvantage of adding an

extra communication layer before reaching the Jahia server. Therefore, for installations that are very

performance sensitive, but do not require a software load-balancer (because for example they use a hardware

balancer such as an F5, http://www.f5.com/ ), using this filter still provides the URL rewriting possibility.

Activating/Deactivating this feature in Jahia is done in the following way:

/webapps/ROOT/WEB-INF/web.xml

Just before:

Comment/Uncomment

<filter> <filter-name>UrlRewriteFilter</filter-name> <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>  <init-param> <param-name>confReloadCheckInterval</param-name> <param-value>20</param-value> </init-param>  <init-param> <param-name>logLevel</param-name> <param-value>DEBUG</param-value> </init-param> </filter>

of 91


Comment/Uncomment

<filter-mapping> <filter-name>UrlRewriteFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>

webapps/ROOT/WEB-INF/urlrewrite.xml

At the end of this file, we have implemented some rules that act as a simple example with what can be done

with this library in Jahia.

Of course you can add as many rules as you wish, bypassing some pages, etc.

It is relatively easy to expand on this example to configure more advanced rules. The Url Rewrite Filter is a

powerful little tool that can do everything the mod_rewrite Apache plugin can do and a lot more! And the nice

thing is that it is Servlet API 2.3 compliant and that it can therefore be installed on any web application server

such as Tomcat, Orion, Resin, WebLogic, Websphere; provided of course the web application server is recent

enough to support this version of the Servlet API.

As the Url Rewrite Filter supports regular expressions, another useful tool to develop and test rules is an

application such as RegexBuddy (for Windows), that lets you develop and test regular expressions. You can

find this tool here: http://www.regexbuddy.com/

2.7.3 Changing port number By default, Jahia comes with Tomcat configured to run on server port 8080, as some machine may already

have a web server running on standard HTTP port 80.

To change the HTTP port of tomcat, open the following file:

conf/server.xml

In the section identified by "Define a non-SSL HTTP/1.1 Connector", you will find the following definition:

<Connector port="9009" protocol="AJP/1.3" redirectPort="8443" enableLookups="false" emptySessionPath="true" URIEncoding="UTF-8" />

Tomcat also listens on a specific port for shut downing. The standard port is 8005. There is no specific reason

to change it unless this port is already used by another application or if you have more than one tomcat running

of 91


on the same system. To change it, search for the following line around the beginning of the server.xml file (in

Tomcat/conf/):

<Server port="8005" shutdown="SHUTDOWN" debug="0">

and change the “port” parameter to whichever port you want tomcat to listen on for shutdown signal.

To configure the wanted port in your application server please modify the following

jahia.properties:

uncomment

"#localAccessUri = http\://localhost\:8080"

and update the port to match yours jahiaWebAppsDeployerBaseURL = http\://localhost\:8080/manager"

update the port to match yours (automatically done if you run install wizard after having changed the port at

application server level)

applicationcontext-services.xml

update used port here:

<bean id="FileListSync" class="org.jahia.services.deamons.filewatcher.FileListSync" factory-

method="getInstance">

[...]

<property name="syncUrl">

<value>http://${localIp}:8080</value>

</property>[...]

</bean>

Please note that when restarting Jahia, launch script will still try to access Jahia on port 8080, so open a

browser and enter the url to access Jahia. For example, if you set Tomcat to run on port 80, the correct URL

would be:

http://localhost:yournewport/

of 91


2.8 Caching INTRODUCTION

Caches are essential to high-performing web systems such as Jahia in order to be able to avoid recreating

dynamic content under large system loads. In the graph above, we can see the basic architecture of the cache

sub-system. All the different cache types are on the top layer, sitting on top of the cache service, which is the

provider for cache implementations. Below this service, various cache implementations may be plugged, and

some of these such as the “Reference Cache” implementation may depend on other Jahia services such as the

“Cluster service” that provides messaging throughout the Jahia cluster installation.

The cache types all use the same cache service that is responsible of providing cache implementations. It is

possible to use the EHCache implementation for the front-end HTML caches and use the ReferenceCache

implementation for the rest of Jahia’s caches. This is the default configuration for Jahia Enterprise Edition v6.1.

of 91


Jahia uses multiple cache layers to optimize the performance of page delivery:

* the browser cache

* front-end HTML caches

* object caches

* database caches

Each of theses cache layers plays a different role in making sure values are only computed once.

2.8.1 The browser cache layer While not integrated in Jahia but in the browser, the browser cache plays a critical role in guaranteeing good

performance for the end-user.

For example, Jahia’s usage of the GWT framework makes it possible for AJAX source code to be aggressively

cached in the browser cache, therefore making sure we don’t reload script code that has not changed. Jahia

also properly manages the browser cache to make sure it does not cache page content that has changed. It

also controls expiration times for cached content, so that the browser does not request content that is rarely

changed.

of 91


2.8.2 The front-end html cache layer Historically, Jahia has had many front-end HTML cache layer implementations. The first was the full-page

HTML cache. While very efficient when a page was already available in the cache, it did not degrade very well

for pages that had a fragment of the HTML that changed from page to page, or from user to user (for example

by displaying the user name on the page). Jahia Enterprise Edition v6.1 combines the sheer efficiency of the

embedded full-page cache with the fragment handling of a page.

This new cache implementation is called the « Container Cache » and integrates fragment caching at a

container level, making the interaction with templates very natural. Template developers usually do not have to

add any markup in order to have their fragments correctly cached. Even when they need to control the

fragment generation, this is much easier to do than in previous versions of Jahia. The “Skeleton Cache” is also

an HTML front-end cache that basically caches everything “around” the fragments, and by regrouping both

cache sub-systems we obtain the equivalent in terms of performance to the full-page HTML cache that existed

in previous versions of Jahia while retaining the flexibility of a fragment cache.

2.8.3 Object caches The next layer below the front-end HTML cache sub-systems are the object caches. This layer handles all Java

objects that represent content objects, users, groups, categories, content definitions, etc. It serves as a layer

on top of the database caches in order to avoid reconstructing objects for each model request. This is all

handled internally by Jahia and it is only important to interact with these caches if integrators are directly calling

Jahia’s API to perform object changes that do not automatically update the caches scheduling / batching.

2.8.4 Database caches The last layer of caches is the database cache layer that makes sure that only minimal interaction with the

database happens. This is important as database communication requires object (de-)serialization and network

communication so the overhead of a database query can be quite substantial. This layer is, in Jahia,

completely handled by the Hibernate ORM layer.

CONFIGURATION

2.8.5 Jahia.properties file You can find it in

webapps/jahia/WEB-INF/etc/config/jahia.properties ###################################################################### ### HTML Container Output cache ##################################### ######################################################################

Where you should have

outputContainerCacheActivated = true

of 91


This part is for setting the expiration delay of your containers as well as setting the cache for live/edit monde.

Setting the cache for edit mode is usually not a good idea as it can lead to some invalidation and inconsistent

behavior, but can in some cases improve the performance of your system.

And

###################################################################### ### Cache settings ################################################### ######################################################################

2.8.6 EHCACHE configuration

webapps/ROOT/WEB-INF/classes/ehcache-hibernate.xml webapps/ROOT/WEB-INF/classes/ehcache-jahia.xml

These files contain some fine tunings for the expiration and management storage of each one of the different

cache entries that EHCACHE handles.

This page http://ehcache.sourceforge.net/documentation/configuration.html

Explains in detail how the storage and configuration can be done. Theses settings have to be reported when

you switch to a clustered mode (please see the cluster configuration part).

2.8.7 Changing the cache provider (for advanced users only) As explained earlier, Jahia supports two cache providers: DEFAULT_CACHE and the EHCACHE. In order to

disable or enable one or another, just modify file

webapps/ROOT/WEB-INF/etc/springapplicationcontext-services.xml

In the JahiaCacheService tag, change each entry in the cacheProviderForCache according to your needs.

For a full explanation of how EH_CACHE works, please refer to the official documentation found here: http://ehcache.sourceforge.net/

2.9 Configuration File Externalization Please note that this feature in available in Jahia since Jahia 6.1.1.3 (r37857)

of 91


DESCRIPTION

2.9.1 Feature functional description The files externalization will allow:

- To isolate the Jahia application as a bundle. This same bundle could be deployed on an identical manner

over environment using application servers such as IBM WAS, Weblogic or JBoss deployment tools.

- To be able to configure cluster nodes independently from one another.

This feature is meant to ease the maintenance or e.g. the process of deployment in a clustered environment.

2.9.2 Feature technical description The feature will externalize the following files. Those files contain most of the JAHIA settings: licensing, clustering, LDAP...

• WEB-INF/etc/config/jahia.properties • WEB-INF/etc/spring/applicationcontext-*.xml • WEB-INF/ect/config/license.xml

CONFIGURATION

2.9.3 jahia.properties In order to externalize the jahia.properties file, the Jahia settings (Properties) have the following lookup order

with later resources overriding the previous, if they are found:

• /WEB-INF/etc/config/jahia.properties : This is the standard properties file, located in the Jahia Web application folder. This is the default file file from which the value are going to be merged.

• /WEB-INF/etc/config/jahia.custom.properties : This file located in the same place as the default one. If this file exist, it will contain parameters overwriting the default ones.

• classpath:org/jahia/config/jahia*.properties : This file is fetched from the CLASSPATH matching the following pattern: org/jahia/config/jahia*.properties. If this pattern is found in the CLASSPATH directories, this file will overwrite the parameters from the properties file located in the Jahia Web application folder (i.e. the CLASSPATH need to be updated with your custom directory).

• file:${jahia.config} : This is a lookup for a file, specified with the Java system property "jahia.config" (e.g. -Djahia.config=/opt/jahia/custom.properties)

2.9.4 Spring bean definitions Spring beans can also be externalized.

• WEB-INF/etc/spring/applicationcontext-*.xml : These are the default spring files containing the Jahia Spring beans.

• classpath*:org/jahia/config/**/applicationcontext-*.xml : Similarly to jahia.properties, Spring is going

to fetch in the CLASSPATH the following pattern: org/jahia/config/**/applicationcontext-*.xml. (i.e the CLASSPATH need to be updated with your custom directory). Spring Beans present in those files will overwrite the Jahia default ones. (e.g CUSTOMCLASSPATH/org/jahia/config/test/applicationcontext-customBeans.xml file)

of 91


2.9.5 Lisence file Finally this feature allows the externalization of the License file. The lookup sequence is listed below and it stops on the first found license file:

• file:${jahia.license} : This is a lookup for a file, specified in with the Java system property "jahia.license" (e.g. -Djahia.license=/opt/jahia/license-pro.xml)

• classpath:org/jahia/config/license*.xml : Similarly to the other ones, Spring is going to fetch in the CLASSPATH the following pattern: org/jahia/config/license*.xml. (i.e the CLASSPATH need to be updated with your custom directory).

• WEB-INF/etc/config/license.xml : the standard location of the Jahia license file

2.9.6 repository.xml The configuration file WEB-INF/etc/repository/jackrabbit/repository.xml cannot be externalized. In case you are

using a clustered architecture, you have to define in this file an identifier for each node in your cluster. If you

want to keep this configuration file the same on each node of the cluster, you can reference the cluster node

identifier defined in jahia.properties. Just define your node identifier as below in repository.xml:

<Cluster id="${cluster.node.serverId}">

2.10 Clustering INTRODUCTION

Deploying Jahia in a cluster is a very powerful way of distributing CPU and memory load to handle larger traffic

sites.

A typical Jahia cluster installation is illustrated in the above graph.

of 91


Jahia nodes communicate directly with each other through direct messaging, but also access shared

resources: a shared file system and the database. The file system is used for the content indexes, as well as

binary content if the server is configured to store it on the file system or in the database if the default

configuration is used. The database stores everything else. It is therefore very important to have a high-

performance database installation as Jahia will depend on it to scale well.

2.10.1 BROWSING nodes Jahia “browsing” nodes are specialized Jahia nodes that only serve as content publishing nodes. They also

interact with portlets to render pages. Using this node specialization allows to separate the browsing load from

authoring and background processing loads.

2.10.2 AUTHORING nodes Jahia “authoring” nodes are cluster nodes that can be used to either browse or edit Jahia content. This is the

most common usage of Jahia nodes, and therefore it is interesting to have multiple instances of these nodes in

order to distribute the load.

2.10.3 PROCESSING nodes In Jahia, long-running tasks such as workflow validation operations, copy and pasting, content import and

indexing are executed as background tasks. This way while these long operations are executed, other nodes

are still able to process content browsing and editing requests.

2.10.4 INDEXING nodes File and content indexation can be a very expensive operation both in terms of CPU usage and memory load.

For example, in order to index PDF files, the server must actually execute the script instructions that are

contained within the file in order to extract the text content. This requires the execution of a full Postscript-like

language, including its memory management and instruction processing, just to extract text content. Indexing

large files also requires memory that cannot be freed until the actual extraction has been completed.

Indexation is usually considered to be an operation that is not needed in real-time, and therefore can run as a

background task. In order to reduce the load on the Jahia servers doing the actual content editing or

processing, it is strongly recommended to install a separate content indexing server, especially if the content

will contain a lot of typical office files.

It is also possible to install multiple indexing nodes, so that there is no single point of failure for this type of

operation.

CONFIGURATION

We tested clustering using the jackrabbit implementation of the jsr 170 norm. The following could be easily

ported to other types of repositories.

of 91


It is essential that you choose during the installation the “Database storage” option for the files and Bigtext.

2.10.5 Jackrabbit The configuration for the repository is situated under

webapps/ROOT/WEB-INF/etc/repository/jackrabbit/repository.xml

Here you should make sure that the files storage is in the database

<param name="externalBLOBs" value="false"/>

Uncomment the following tag



To have something like

<Cluster id="qa-j3"> <Journal lass="org.apache.jackrabbit.core.journal.DatabaseJournal"> <param name="driver" value="javax.naming.InitialContext" /> <param name="schema" value="mysql" /> <param name="url" value="java:comp/env/jdbc/jahia" /> <param name="revision" value="${rep.home}/revisionNode"/> <param name="janitorEnabled" value="true"/> </Journal> </Cluster>

Where id is the name you have chosen for your node (will be used in the Jahia.properties file).

Since Jahia 6.1.1.3 (r37857), you have also the possibility to reference the node identifier defined in

jahia.properties instead of duplicating it here.

<Cluster id="${cluster.node.serverId}">

of 91


2.10.6 Jahia.properties Here is where you define your cluster nodes under

###################################################################### ### Cluster settings ################################################ ######################################################################

The serverId should be the one you have chosen in repository.xml

Here you also set the configuration for your processing node by setting the property to true, as well as the IPs

of the other nodes in the cluster

Also for the right caching, please change the settings found under

###################################################################### ### EhCache settings ############################################### ######################################################################

Please note that Since Jahia 6.1.1.3 (r37857), you need to modify the indexation policy section as well. Those

settings are located under:

###################################################################### ### Indexation policy ############################################### ######################################################################

2.10.7 Indexing configuration The configuration is located under :

webapps/ROOT/WEB-INF/etc/spring/applicationcontext-indexationpolicy.xml

localIndexing

Put 1: index, 0: do not index, just read (I.E when sharing a same index directory in a clustered environment)

multipleIndexingServer

Put 0: Only one indexing server mode: If you only have one single indexing server, then you should use this

mode so that the indexing jobs queue can be handled in an optimized way for better performance.

1: Multiple indexing server mode: If you have more than one indexing server, then you MUST use this mode.

Since Jahia 6.1.1.3 (r378579), these settings are moved to Jahia.properties file.

of 91


2.10.8 Sharing webapps Web application needs to support clustering on their own to be able to fully work in a clustered Jahia

environment. Once a webapp has been deployed on a node (the deployed webapp will be available in

tomcat\webapps), you will need to manually copy the directory where the webapp has been deployed to all

other nodes in the cluster.

2.10.9 Sticky sessions If you are using a hardware or software load balancer in front of Jahia to handle distribution of load among all

Jahia nodes in the cluster, you will need to activate "sticky sessions" on Tomcat and the load balancer. This is

required to force an open session to make all requests on the same server for the time of the session.

On Tomcat, This is done by adding a unique jvmRoute in the server.xml file. Uncomment this part:



where jvm1 is the name of the worker as declared in the load-balancer.

you can always see the reference guide for the configuration of the load balancer on the apache web site

2.10.10 Troubleshooting cluster configuration Most cluster configuration issues rise up from problems with the configuration of the cluster. Make sure you

have put all the ip addresses along with the right ports on the Jahia.properties of all the cluster nodes.

2.11 LDAP LDAP is an application protocol for querying and modifying directory services running over TCP/IP. Jahia has

default connectors to retrieve users/groups from an LDAP server. Jahia supports most LDAP servers right out

of the box, including OpenLDAP and ActiveDirectory. It is most commonly used with SSO technologies to

provide a seamless experience to end-users. Starting from Jahia Enterprise Edition v6.1, the LDAP

configuration if now centralized in the same file.

webapps/ROOT/WEB-INF/etc/spring/applicationcontext-services.xml

Jahia can manage LDAP groups as well as LDAP users.

of 91


The configuration can be set by not commenting the proper tags, and updating the mappings inside the

JahiaUserManagerLDAPProvider and the JahiaGroupManagerLDAPProvider beans according to your LDAP

configuration.

• The "JahiaUserManagerLDAPProvider"

<bean id="JahiaUserManagerLDAPProvider" class="org.jahia.services.usermanager.JahiaUserManagerLDAPProvider" parent="jahiaServiceTemplate" factory-method="getInstance"> <property name="cacheService" ref="JahiaCacheService"/> <property name="key" value="ldap"/> <property name="defaultProvider" value="false"/> <property name="readOnly" value="true"/> <property name="priority" value="2"/> <property name="ldapProperties"> <map> <entry key="context.factory" value="com.sun.jndi.ldap.LdapCtxFactory"/> <entry key="url" value="ldap://127.0.0.1:389/"/> <entry key="authentification.mode" value="simple"/> <entry key="public.bind.dn" value=""/> <entry key="public.bind.password" value=""/> <entry key="uid.search.attribute" value="cn"/> <entry key="uid.search.name" value="dc=jahia"/> <entry key="search.countlimit" value="100"/> <entry key="search.objectclass" value="person"/> <entry key="search.wildcards.attributes" value="ou, cn, o, c, mail, uid, uniqueIdentifier, givenName, sn, dn"/> <entry key="firstname.attribute.map" value="givenName"/> <entry key="lastname.attribute.map" value="sn"/> <entry key="email.attribute.map" value="mail"/> <entry key="organization.attribute.map" value="ou"/> </map> </property> </bean>

• "JahiaGroupManagerLDAPProvider"

<bean id="JahiaGroupManagerLDAPProvider" class="org.jahia.services.usermanager.JahiaGroupManagerLDAPProvider" parent="jahiaServiceTemplate" factory-method="getInstance"> <property name="cacheService" ref="JahiaCacheService"/> <property name="key" value="ldap"/> <property name="defaultProvider" value="false"/> <property name="readOnly" value="true"/> <property name="priority" value="2"/> <property name="groupManager" ref="org.jahia.hibernate.manager.JahiaGroupManager"/> <property name="jahiaUserManagerService" ref="JahiaUserManagerService"/> <property name="ldapProperties"> <map> <entry key="context.factory" value="com.sun.jndi.ldap.LdapCtxFactory"/> <entry key="url" value="ldap://127.0.0.1:389/"/> <entry key="authentification.mode" value="simple"/> <entry key="public.bind.dn" value=""/>

of 91


<entry key="public.bind.password" value=""/> <entry key="search.attribute" value="cn"/> <entry key="search.name" value="dc=jahia"/> <entry key="search.countlimit" value="100"/> <entry key="search.objectclass" value="groupOfUniqueNames"/> <entry key="members.attribute" value="uniqueMember"/> <entry key="dynamic.search.objectclass" value="groupOfURLs"/> <entry key="dynamic.members.attribute" value="memberurl"/> <entry key="preload" value="true"/> <entry key="search.wildcards.attributes" value="cn,description,uniqueMember"/> <entry key="groupname.attribute.map" value="cn"/> <entry key="description.attribute.map" value="description"/> </map> </property> </bean>

• Two entry keys for each of the user and the group

<entry key="ldap" value-ref="JahiaGroupManagerLDAPProvider"/>

And

<entry key="ldap" value-ref="JahiaUserManagerLDAPProvider"/>

2.12 Single Sign-On: CAS The Central Authentication Service (CAS) is a single sign-on protocol for the web. Its purpose is to permit a

user to access multiple applications while providing their credentials (such as user id and password) only once.

When the client visits Jahia and wants to authenticate, Jahia redirects the user to the CAS server. CAS

validates the client's authenticity, usually by checking a username and password against a database (such as

LDAP or Active Directory).

If the authentication succeeds, CAS returns the client to Jahia, passing along a security ticket. Jahia then

validates the ticket by contacting CAS over a secure connection and providing its own service identifier and the

of 91


ticket. CAS then gives the application trusted information about whether a particular user has successfully

authenticated.

2.12.1 Jahia

Step 1: The first folder to configure is the cas.properties located under

webapps\ROOT\WEB-INF\etc\cas

Here the values that you would want to change are:

cas.jahia.serviceUrl= http://servername:8080/cms

be careful as servername should be the same name as the one you have in your administration interface in

Jahia

cas.server.validateUrl=https://serveurCAS:8443/cas/serviceValidate

(must be https !)

cas.server.loginUrl= https://serveurCAS:8443/cas/login

Step 2: also make sure to have the CAS pipeline under applicationcontext-pipelines.xml in

webapps\ROOT\WEB-INF\etc\sping

to have something like

<bean id="authPipeline" class="org.jahia.pipelines.impl.GenericPipeline"> <property name="name" value="authPipeline" /> <property name="valves"> <list>

of 91


<bean class="org.jahia.params.valves.CasAuthValveImpl" /> <bean class="org.jahia.params.valves.TokenAuthValveImpl" /> <bean class="org.jahia.params.valves.LoginEngineAuthValveImpl" /> <bean class="org.jahia.params.valves.UserAliasingEngineAuthValveImpl" /> <bean class="org.jahia.params.valves.SessionAuthValveImpl" /> <bean class="org.jahia.params.valves.CookieAuthValveImpl" /> <bean class="org.jahia.params.valves.ContainerAuthValveImpl" /> <bean class="org.jahia.params.valves.JCIFSAuthValveImpl" /> </list> </property> </bean>

Step 3: Add the login link in a Jahia template :

<%org.jahia.data.JahiaData jData = (org.jahia.data.JahiaData)

request.getAttribute("org.jahia.data.JahiaData");%>

<a href="javascript:<%=jData.gui().html().drawLoginLauncher()%>">Se loguer</a>

This page http://www.ja-sig.org/wiki contains many information in order to configure your CAS server.

A good architecture would separate the CAS server from the other application servers.

2.12.2 Troubleshooting If you have errors of the form:

org.jahia.exceptions.JahiaException: User message=Cannot validate CAS credentials, System

message=Cannot validate CAS credentials, root

It is most probably due to your ssl certificate and that the JVM that runs the Jahia does not recognize it.

Refer to http://www.jasig.org/cas/server-deployment/solving-ssl-issues for more details.

3 Fine Tuning After having implemented all your templates and are satisfied with your website, there can be some

modifications to be done in order to enhance the performance of your server

Before changing any values on your production server, you should ask yourself the following questions:

• How many editors have you got working simultaneously on the system?

• What is the number of authenticated users that can log into your system (in general, not necessarily at the same time)?

of 91


• What is the number of pages that you have in your system and if they contain a lot of resources (pdf files, etc)?

As a general rule, in order to test the performance of any system running Jahia, here are the issues that need

to be addressed:

1. Tomcat and the amount of virtual memory (typically the Xmx part in the catalina.bat file)

2. The database and its default settings

3. Jahia properties configuration

The values given here are the high values and have been tested, but that does not mean that this corresponds

to the values you should set. The way to find the proper values that will be fit for your system is to increase

progressively and once at a time the values set here (except for the server.xml and database pool size, they go

by pair). Then run a load test (baring in mind the answers to the questions at the beginning of this documents)

and see if it corresponds to your expectations.

3.1 Tomcat 3.1.1 bin/catalina.sh We usually recommend raising the amount of virtual memory (Xmx parameter) in your bin/Catalina.sh file to

2048 or even 4096.

It is not necessarily true that the more amount of virtual memory you give to your system the faster you get, as

sometimes having a lot of memory can benefit you in the beginning but then garbaging may take longer, which

will make your server unavailable for a longer period of time.

of 91


3.1.2 conf/server.xml Here you can increase the amount of maxThreads to 300 (was 150) and the amount of acceptCount to 300 as

well. These setting are the ones handling the connections to your database. MaxThreads is the maximum

number of threads processing requests in Tomcat, whether serving pages from Jahia cache or not. If this one

is exceeded then errors will be sent to the client.

On the other hand raising this number may not bring the wanted effect, if you leave the

maxParallelProcessings = 40 in jahia.properties, as no more than that number will do the real work, while the

other threads will queue. But we will talk about the configuration of Jahia.properties further in this document.

3.2 Database As we have increased the amount of threads in Tomcat we have to increase the pool of connections database.

We usually have the following values for Mysql:

key_buffer = 384M max_allowed_packet = 512M table_cache = 512 sort_buffer_size = 2M read_buffer_size = 2M read_rnd_buffer_size = 8M myisam_sort_buffer_size = 64M

of 91


thread_cache_size = 8 query_cache_size = 128M thread_concurrency = 8 #lower_case_table_names=1 max_connections=3000

3.3 Jahia.properties This file is located under

webapps/ROOT/WEB-INF/etc/config

Here you should increase the following values for your server

###################################################################### ### Concurrent processing options #################################### ######################################################################

of 91


# # This variable controls how many threads are allowed to do heavy weight # processing (page creation not served from the cache) - maxParallelProcessings = 10 + maxParallelProcessings = 100 # This variable controls how long threads are waiting to be able to start # generating pages in heavy load situations (value in milliseconds) - pageGenerationWaitTime = 120000 + pageGenerationWaitTime = 50000

Normally many requests will be served from cache and should not use many resources.

These value controls how many parallel threads will be allowed to start rendering pages not coming from

cache, meaning that they will open DB connections to obtain the content from the DB. Most customers with

heavy load have already raised that value, but when you do that you will have to take care that the DB

connections are raised, too. The second parameter is the maximum wait time to wait until a new heavy

processing thread is available, otherwise an error is sent to the client.

maxParallelProcessings in jahia.properties should not be bigger than maxThreads value in server.xml

3.3.1 Output cache expiration In order to avoid the cost of calculating references of content used on multiple pages, the output cache should

be set to expiration mode instead of the default immediate invalidation mechanism.

The output cache must also be updated

outputCacheExpirationOnly=true outputCacheDefaultExpirationDelay=3600000

The last value is in milliseconds and represents an expiration delay of an hour.

You might have to adjust this setting to your own needs.

3.3.2 Session Duration

editModeSessionTimeout=7200

This last setting will set the session duration for editing users to 2 hours instead of the default session

expiration

in tomcat/conf/web.xml the following setting should be lowered from 30 minutes to something like 10 minutes to

save memory: 10

of 91


3.3.3 Development mode Setting the Development mode to false enhances the performance of your server as when set to true, this

setting flushes the html cache each time you change the operation mode (live/edit).

4 Monitoring There are multiple ways of monitoring a Jahia installation's behavior in real-time, that we will present below:

• JAMon monitoring

• Monitoring server memory, CPU usage, threads and sessions

• Performing Stack trace dumps

of 91


• Performing Memory dumps

• Java Profilers

Also, if you have identified an issue with a Jahia installation and want to communicate it back to us, we also

have a section below that describes what is required to efficiently provide us with the data that will help us

assist you in a timely manner.

4.1 JAMon Jahia includes a tool to monitor in real-time the performance of it's innards, in order to be able to better detect

where time is spent, and to take appropriate actions.

What this monitoring system provides is real-time gathering and reporting of the time spent in Jahia's back-end

services, as well as the number of times they were called. It uses for this the excellent JAMon library, which

provides the facilities to generate HTML, XML or even Microsoft Excel reports. For more information on this

library, please check out their web site.

of 91


In this first version, only monitoring of Jahia's services is possible, but we might extend it to cover more code.

4.1.1 Activating / deactivating monitoring By default the statistics gathering interceptor is already integrated into Jahia, but does nothing until we change

the logging level on it's particular implementation. Jahia ships with this interceptor de-activated as the activation

can introduce some performance cost. Fortunately it is possible, due to Jahia's automatic reloading of logging

configuration at runtime, to modify the configuration while Jahia is running.

To activate statistics gathering:

Modify the

webapps/ROOT/WEB-INF/etc/config/log4j.xml

to change the logging level for the interceptor to DEBUG, as follows :

<category name="org.jahia.spring.aop.interceptor">  <priority value="debug"/> </category>

Save the changes, Jahia will pick up the modified log4j configuration after 1 minute, and you will then be able

to use the reporting interface to view results.

To deactivate statistics gathering:

As in the previous step, simply change the logging level back to info and save the file. After 1 minute, Jahia will

pick up the change.

4.1.2 Accessing the reporting user interface In Tomcat's users file, conf/tomcat-users, make sure you have a user that has the "manager" role. Here is an

example :

<user username="Jahia" password="4Kz2kE2cy4" roles="manager"/>

Make sure you noted the username and password, because you will need it to access the reporting JSP. If you

do not have such an entry, you will have to create it once, and then restart Jahia. Be sure you choose a

password that is strong, because the manager role also gives you access to Tomcat's deployment interface.

You should now be able to browse to:

of 91


http://localhost:8080/monitor/JAMonAdmin.jsp

and use the username and password from the Tomcat configuration file.

The view presents a table with at the left the methods intercepted in the services. You can see the number of

call to those methods, as well as the average and cumulative times spent in those.

4.1.3 Steps to completely deactivate the service interception.

By default, Jahia is shipped with the service interceptor activated. The performance cost of this system should

be minimal, but you might want to deactivate it to minimize processing on a production system that is operating

within it is target performance. We describe here how to completely remove the overhead introduced by this

system.

In the file tomcat/webapps/ROOT/WEB-INF/etc/spring/ applicationcontext-manager.xml comment the

following lines :

<bean id="performanceInterceptor" class="org.jahia.spring.aop.interceptor.SilentJamonPerformanceMonitorInterceptor"> <property name="useDynamicLogger"><value>false</value></property> </bean>

Still in tomcat/webapps/ROOT/WEB-INF/etc/spring/ applicationcontext-services.xml, in the proxyTemplate

bean, comment the following lines:

<bean id="proxyTemplate" abstract="true" class="org.springframework.aop.framework.ProxyFactoryBean"> <property name="interceptorNames"> <list> <value>performanceInterceptor</value> </list> </property> <property name="proxyTargetClass" value="true" /> </bean>

4.2 Monitoring server memory, CPU usage, threads and sessions Unfortunately though, JAMon will not give you more detailed information about the status of sessions, memory,

threads, etc. For this you can install different tools on your server to help you out. First of all, there is

MessAdmin, which is quite minimal in functionality, but allows you to see and track session data. You can also

send messages to users, for example to inform them that maintenance will take place. MessAdmin does all this

through usages of filters, so not only it is quite transparent to install, but it is also portable to a lot of application

servers.

Some of the tools available in JDK 5 and 6 that are very interesting are JConsole or VisualGC

of 91


One of the best tools, but is Tomcat specific, is LambdaProbe. If you activate Tomcat's JMX interfaces, you can even monitor garbage collection internal spaces, such as PermGen, Eden, etc..

4.2.1 Monitoring Tomcat and Jahia through LambdaProbe If you want to monitor Jahia's execution with LambdaProbe or JConsole, modify your Tomcat's catalina.bat

(catalina.sh) script to add the following:

-Dcom.sun.management.jmxremote

to the line :

set CATALINA_OPTS=%CATALINA_OPTS% -Dsun.io.useCanonCaches=false -Xms64m -Xmx1024m -XX:MaxPermSize=128m -server -Dhibernate.jdbc.use_streams_for_binary

You can then view internal thread and memory processing of your server. If you want to configure remote

access monitoring, this is quite more complicated, and the best thing is that you read the documentation

provided by Sun for monitoring JVMs.

You can then start your Jahia, and then start JConsole or use LambdaProbe to view the current status of your

server.

You can find installation instructions for LambdaProbe here. For JConsole it is simply included in JDK 5 and

up, so you just need to start it and connect it to Tomcat once the above configuration in the catalina.bat(.sh)

has been done.

4.3 Stack trace dumps Stack trace dumps are a very useful way of figuring out exactly what the JVM is executing at a specific point in

time. Basically the JVM has a way of dumping onto the console output a list of all the threads currently

executing with, for each thread, a detailed stack trace of where in the code each thread is currently. For more

detailed information on stack traces, please check this resource.

Performing a stack trace dump is different on various platforms:

4.3.1 UNIX On UNIX platforms you can send a signal to a program by using the kill command. This is the quit signal, which

is handled by the JVM. For example, on Linux you can use the command kill -QUIT process_id, where

process_id is the process number of your JVM. Don't be alarmed by the fact that the command is called "kill",

despite the name, all this command will do is perform a stack trace dump and the JVM will continue executing.

of 91


Alternatively you can enter the key sequence <ctrl>\ in the window where the JVM was started. Sending this

signal instructs a signal handler in the JVM, to recursively print out all the information on the threads and

monitors inside the JVM.

4.3.2 Windows To generate a stack trace on Windows 95, or Windows NT platforms, enter the key sequence <ctrl><break> in

the window where the Java program is running, or click the Close button on the window.

The output of the stack trace will go to the console output, so under Windows it will be displayed in the JVM

window, and under UNIX it will be in tomcat/logs/catalina.out.

Once the dump has been performed, you can look for threads that are blocked, or see the amount of threads

that are performing some operations, which might not be expected.

4.4 Memory dumps In order to analyze the memory usage of a JVM, it is possible to perform memory dumps that can then later be

analyzed to determine if the application if behaving as expected, or if a data structure is eating up too many

resources.

There are two ways of performing memory dumps with the JVM:

1. via Java VM parameters : o -XX:+HeapDumpOnOutOfMemoryError writes heap dump on OutOfMemoryError

(recommended) o -XX:+HeapDumpOnCtrlBreak writes heap dump together with thread dump on CTRL+BREAK

(recommended) 2. via tools:

o Sun JMap: jmap.exe -dump:format=b,file=HeapDump.hprof <pid> o Sun JConsole: Launch jconsole.exe and invoke operation dumpHeap() on HotSpotDiagnostic

MBean

of 91


The heap dump will be written to the working directory.

Once you have the heap dump, you can either use a Java profiler (see below) to load up the dump, but they

usually have problems analyzing large files. A much better tool is the SAP Memory Analyzer, available here:

SAP Memory Analyzer

What you will be looking for in memory dumps is the largest structures in memory. Usually these will be cached

objects, but they may also be objects referenced from the sessions.

4.5 Java profilers The most powerful tool to analyze in real-time what is going on inside a Jahia installation is of course a JVM

profiler. There are multiple tools that exist, but we recommend YourKit Java Profiler, which is a commercial tool

that can be used even in production with lesser performance impacts.

You can find a more extensive list of profilers here:

• Free Profilers

• Commercial Profilers

4.6 Others Issues

The best way to get support for your issues is to contact us for a support agreement. Please see this page for more information.

of 91


If you have a commercial support contract, you will get your own space to submit issues that will be handled

according to our SLA. Otherwise you can report issues to the general JIRA projects, but here there will be no

guarantee as to how and when the issue will be handled. When submitting an issue to our JIRA Issue tracker,

make sure you include as much information as possible, including:

• A detailed description of your environment including the version number and patches (J2EE server, JDK, OS) as well as memory and architecture (32-bit, 64-bit)

• A detailed (or complete) log file, including date and times at which the problem occurs to be able to corroborate with log file

• A list of steps to reproduce the problem (if not random)

• A stack trace dump

• If dealing with an OutOfMemory issue, please include a memory dump

As a basic rule, we also prefer to have too much information than too little.

5 Frequently asked questions (FAQ)

5.1 How to backup my Jahia? Backing up your system is useful in many cases as it minimizes the risk of loosing all your data, whether it is in

the database or server side.

Database

A database dump contains a record of the table structure and/or the data from a database and is usually in the

form of a list of SQL statements. It is most often used for backing up a database so that its contents can be

restored in the event of data loss (or in our case reusing an environment). Database dumps can be performed

anytime, even when the Jahia server is running, but it is usually preferable to shut down your Jahia before

dumping your database.

There are many software (proprietary or Open Source) that can perform a database dump for all types of

databases. We will take here the example of MySQL.

mysqldump -urootUser -p jahia6_v1 > jahia6_v1.sql

of 91


Your database configuration is located under

webapps/META-INF/context.xml

Jahia core data files

If you have chosen the filesystem storage for your BigText (variable bigtext.service set to FileJahiaText in your

Jahia.properties file) and your files (variable external BLOBs to true in your repository.xml file) in your

configuration, then you should also back up all the folders under:

webapps/ROOT/WEB-INF/var/content/bigtext/

webapps/ROOT/WEB-INF/var/repository/workspaces/

You can also backup the following folder, which contains your site(s) indexes. If you do not, you will be able to

trigger the regeneration of those indexes from the Jahia Administration Center. So, this folder is usually backed

up only when it is mandatory that the search engine is immediately up and running when you restore your

system in production.

webapps/ROOT/WEB-INF/var/search_indexes/

Templates

Your templates are all situated under the folder:

webapps/ROOT/templates

And are shared among all your virtual sites. This folder should also be backed up if your templates are not

already saved in a version control system (in this case, if the deployed templates are not always the last

development version, you just need to keep which version of your templates you deployed in your server).

Web applications/portlets

If you have no web additional applications (or portlets) used inside your Jahia server, you can skip this part. All

default Jahia webapps are embedded inside the Jahia application and do not require any backup.

All the additional webapps you may have deployed will be located here:

webapps/

of 91


Each webapp directory name contains the name of the application. For example, if you have added a “Time

Reporting” the directory name will be “TimeReporting”.

Webapps are accessible across any virtual sites.

You can backup all web applications or only the one you use. If you installed some third party portlets, be sure

to check on their respective documentation. Depending if the webapp stores some information, the way you

backup the webapp will be different. If the webapp stores nothing, you can either backup the .war file you had

used to deploy the portlet, or the subfolder of “webapps/” in which the webapp has been deployed. If the

webapp stores some data, you will also have to backup it.

Custom classes/ResourceBundles

Your templates can require some additional classes, and/or some specific Resources Bundles. You can also

have updated our Resources Bundles, or added some additional translations. If you use a version control

system, just check that all those elements are versioned and stored in it. If they are, just keep which version

you had deployed. Otherwise, backup those elements each time you deploy a new version (the templates

Resources Bundles may be embedded inside your templates, and would be in this case already backed up

with your templates).

Configuration files

All the configuration files are situated under

webapps/jahia/WEB-INF/etc/

These contain all the information regarding your LDAP, SSO database storage and more specifically the

Jahia.properties file.

If you are under UNIX, for regular backup of you Jahia data, you can for instance create a script file and run it

through a Cron job. A typical example of this script could be :

DAY=`date +%u` /bin/tar cvfz /home/backup/tomcat_$DAY.tar.gz /home/jahia/tomcat/ #list of folders to copy

5.2 How to restore an environment from a backup? Install the same Jahia version with a new and empty database.

of 91


During the configuration wizard, it is essential that you choose the same type of database, and the same

database options as when you installed your previous environment.

If you do not remember, open webapps/ROOT/WEB-INF/etc/repository/jackrabbit/repository.xml and check the

following parameter:

<param name="externalBLOBs" value="false"/> “False” means that you have chosen the storage of Files in the database.

Open webapps/ROOT/WEB-INF/etc/config/jahia.properties and check the following parameter:

bigtext.service = DBJahiaText

“DBJahiaText“ means that you have chosen the storage of Bigtext in the database.

At the end of the Configuration Wizard, when you can choose how to create your first virtual site, stop your

Jahia application without creating any site.

Restore the dump.

Update your database connection url / credentials in webapps/META-INF/context.xml to make Jahia use

the database you have restored.

Apply your specific configurations on your new installation.

When getting from a service pack to another, some configuration files may have changed (see the change log

for this). This means that when migrating from an old version of Jahia to a newer one, simply copying and

pasting the configuration files may not work or may lead to startup errors. You will save time if you document

your specific configurations, so that you can easily apply it on a new installation.

Deploy your templates set if this one is different than the provided ones (please refer to the templates

deployment guide for this) as well as any other resource bundles/classes you have created.

If you have chosen file system storage for Bigtexts, copy your WEB_INF/var/content/bigtext/ from your former installation.

If you have chosen the file system storage for the file you may upload in the Document Manager, copy your WEB_INF/var/repository/workspaces/ folder as well.

You can also copy your Lucene search indexes (folder WEB_INF/var/search_indexes/ ), or trigger a reindexation for each site from the Jahia Administration Center.

of 91


You can now restart your reinstalled Jahia application (and reindex your sites if it is the way you have chosen to restore your indexes).

5.3 How to upgrade to a newer version? This topic handles migrations from Jahia v6.0.0 EE to Jahia v.6.1.0 EE with the latest hotfix patch.

5.3.1 Using the upgrade patches Go in the “Download Area” section / “Jahia v6” / “Download” in the extranet. You will be able to download the

installation package for the latest version of Jahia v6, but also the latest hotfix patch for this same version. If

you use an older version of Jahia, you will need first to apply an upgrade patch (available in the “archive page”)

to upgrade your installation to this latest version, before applying the latest hotfix.

You are using Jahia v6.1.0 EE (without any hotfix or a hotfix which is not the latest one)

Download the latest hotfix patch from “v6 / download” page and apply it, following the associated

ReadMe.

You are using Jahia v6.0.1 EE (with or without hotfix)

Download the upgrade patch from 6.0.1 to 6.1.0 from “v6 / download / archive” page and apply it,

following the associated ReadMe.


ReadMe.

You are using Jahia v6.0.0 EE (with or without hotfix)






ReadMe.

5.3.2 Reinstalling your environment and using the XML import feature to recover your content Export your site(s) from your former installation

Install the new Jahia version with a new and empty database.

of 91


During the configuration wizard, you can choose similar database configuration (same database type, same

options regarding filesystem vs database storage), but also different configurations.

Apply your specific configurations on your new installation.

When getting from a service pack to another, some configuration files may have changed (see the change log

for this). This means that when migrating from an old version of Jahia to a newer one, simply copying and

pasting the configuration files may not work or may lead to startup errors. You will save time if you document

your specific configurations, so that you can easily apply it on a new installation.

Deploy your templates set if this one is different than the provided ones (please refer to the templates

deployment guide for this) as well as any other resource bundles/classes you have created.

Import your website(s) from the Administration Center.

5.4 Modifying the Logging Level When you install a release of Jahia, the logging level is set to the minimum to avoid slowing down Jahia. If you

need to increase it for debugging purpose, you need to modify the file log4j.xml which is in the following

directory:

TOMCAT_HOME/webapps/ROOT/WEB-INF/etc/config

Log4J defines some logging levels as follows (from the more to the less verbose):

ALL < DEBUG < INFO < WARN < ERROR < FATAL < OFF

At the bottom of the file, you have the <root>... </root> part. Change the <priority value="info"/> to <priority

value="debug"/> for example to have more debugging information in the console. You can also change this

parameter for some specific part of Jahia like Slide or pdfbox. You can even add your own logger on a specific

set of classes, for example:

<category name="org.apache.axis">

<priority value="info"/>

</category>

By default logs are outputted to the standard out, which is normally the console. Under Windows logs will be

displayed in the DOS window where Tomcat is running. On Linux, logs will be outputted to catalina.out file. As

of 91


Jahia uses Apache log4J for its logging system, you can use tools like Chainsaw (part of the log4J project) to

better work with logging messages.

You can change “on-the-fly” the log-level of Jahia without having to shutdown and restart it. This is very useful

when you need to have extra logs on a production server but do not want to restart it just for this. Jahia watch

for changes in the log4j.xml file every 60 seconds, so once you have changed the log level, you will need to

wait a few seconds before the changes will be effective.

Do not forget to change back the values to INFO, as DEBUG log level has a pretty important impact on

performance.

5.5 Upgrade the Tomcat Application Server How to deploy Jahia into a different Tomcat server?

If you want to upgrade the Tomcat application server or install Jahia in a stand-alone Tomcat installation,

several changes need to be done. Below you will find a description of all files that need to be moved or

changed if you want to have Jahia running with a standalone version of Tomcat (ie. a version downloaded from

the Apache Jakarta website).

Copy startup and configuration files

The following files need to be copied from the Tomcat provided with Jahia to the Tomcat standalone

installation:

jahia-sync-nodes.xml jahia.ico jahiaInstallation.bat jahiaInstallation.sh jahiaServer.bat jahiaServer.sh shutdown.bat shutdown.ico shutdown.sh bin/catalina.sh bin/catalina.bat conf/server.xml conf/tomcat-users.xml conf/web.xml

Copy libraries

The following libraries need to be copied from the Tomcat provided with Jahia to the Tomcat standalone

installation:

of 91


activation-*.jar castor-*.jar ccpp-*.jar commons-logging-*.jar jaxb-impl-*.jar log4j-*.jar pluto-*.jar portlet-*.jar stax-*.jar xercesImpl-*.jar xmlParserAPIs-*.jar

Copy the Jahia web application

The following folder needs to be copy from the default Jahia installation to the standalone Tomcat installation:

webapps\<context-name> (ROOT by default) webapps\config

To launch Jahia, please run jahiaServer.bat or sh depending of your operating system.

If you installed Tomcat with the Windows Service installer you should only use the Windows service to start it.

You will need to set the command line parameters (used in catalina.bat) like described here:

http://tomcat.apache.org/tomcat-6.0-doc/windows-service-howto.html

9 route des Jeunes, CH-1227 Les acacias Geneva, Switzerland

www.jahia.com The Company website

www.jahia.org The Community website

documentation configuration and fine tuning guide … · documentation configuration and fine...

Documents