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.
Jahia
May 2011
9 route des Jeunes,
CH-1227 Les acacias
Geneva, Switzerland
www.jahia.com
The Company website
www.jahia.org
The Community website
September 2009
Summary
Summary .............................................................................................................................................................. 2
1
2
Overview ....................................................................................................................................................... 6
1.1
Introduction ............................................................................................................................................ 6
1.2
What’s in this documentation? ............................................................................................................... 6
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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 2 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 3 of 91
2.10.8
Sharing webapps .......................................................................................................................... 67
2.10.9
Sticky sessions ............................................................................................................................. 67
2.10.10
3
2.11
LDAP ................................................................................................................................................ 67
2.12
Single Sign-On: CAS ........................................................................................................................ 69
2.12.1
Jahia ............................................................................................................................................. 70
2.12.2
Troubleshooting ............................................................................................................................ 71
Fine Tuning ................................................................................................................................................. 71
3.1
4
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
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
4.3
5
Troubleshooting cluster configuration ....................................................................................... 67
Monitoring Tomcat and Jahia through LambdaProbe................................................................... 80
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
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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 4 of 91
5.4
Modifying the Logging Level ................................................................................................................ 88
5.5
Upgrade the Tomcat Application Server .............................................................................................. 89
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 5 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).
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 6 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/
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 7 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)
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 8 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 9 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 10 of 91
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`--
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|-|
|-|
|-|
|-|
|-|
|-|
|-|
|-|
|-|
|
|
|
|
|-|
|-|
|-|
|-|
|-|
|
|
|
|
|
|
|
|
|-|
|-./work
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|-|-`--
|
|-- ./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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 11 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 subdirectory 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 selection 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 12 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
XX:MaxPermSize=192m
-server
–Xms4096m
–Xmx4096m
-Djava.awt.headless=true
-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 ).
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 13 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.configur
e.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>
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 14 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>
<!-- Tomcat 6.0 development -->
<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/apachetomcat-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>
<!-- Jahia plugin -->
<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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 15 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 :
<!--
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 16 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
<param
<param
<param
<param
name="driver" value="oracle.jdbc.OracleDriver" />
name="schema" value="oracle" />
name="url" value="jdbc:oracle:thin:@ORACLE_SERVER_IP_ADDRESS:1521:test" />
name="user" value="username" />
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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 17 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/
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 18 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 19 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 20 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 :
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 21 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 22 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 23 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 :
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 24 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”
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 25 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”
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 26 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 27 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 28 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 29 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:
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 30 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 31 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”
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 32 of 91
5. Leave all the defaults on the screen below and click “Next”
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 33 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 34 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:
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 35 of 91
10. Your screen should look like this (check the authentication method in the resources is properly set)
11. Click “Next”
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 36 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”:
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 37 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 38 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 39 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 40 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/plutotaglib/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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 41 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 42 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>
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 43 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>
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 44 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 45 of 91
•
Go to “Deployment” section of your weblogic domain and deploy your Jahia application by selecting
your jahia.ear folder as application path
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 46 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:
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 47 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 48 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
and
<JBOSS_HOME>/bin/run.conf.bat
(for
also
JBoss
files
4.3.0
there
could
be
alternatively
<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
<JBOSS_SERVER_CONFIG>/deploy/jboss-web.deployer/ROOT.war
2.5.3
a)
Web
application,
rename
the
folder
to e.g. jboss.war
Create datasource
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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 49 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
2.5.4
configuration from in-process to server mode.
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
<JBOSS_SERVER_CONFIG>/conf/roles.properties
for
the
user
Jahia
into
your
file
(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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 50 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 jaxbimpl.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/DERBY3887).
2.5.6
Set
Modify files
the
server
parameter
to
JBoss
and
adjust
the
serverHomeDiskPath
<JBOSS_SERVER_CONFIG>/ROOT.war/WEB-INF/etc/config/jahia.properties
<JBOSS_SERVER_CONFIG>
parameter
in
to have the absolute path to the
folder, for example:
server
serverHomeDiskPath
www.jahia.com > The Company website
www.jahia.org > The Community website
=
=
JBoss
/opt/jboss-4.2.3.GA/server/default/
Page 51 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 52 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 53 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>
<!-- Disable cache for JSPs and '.nocache.' GWT resources -->
<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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 54 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>
<!-- set the amount of seconds the conf file will be checked for reload can be a
valid integer (0 denotes check every time,
-1 denotes no reload check, default -1) -->
<init-param>
<param-name>confReloadCheckInterval</param-name>
<param-value>20</param-value>
</init-param>
<!-- sets up log level (will be logged to context log)
can be: TRACE, DEBUG, INFO (default), WARN, ERROR, FATAL, log4j, commons, sysout:{level}
(i.e., sysout:DEBUG)
if you are having trouble using normal levels use sysout:DEBUG
(default WARN) -->
<init-param>
<param-name>logLevel</param-name>
<param-value>DEBUG</param-value>
</init-param>
</filter>
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 55 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 56 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" factorymethod="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/
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 57 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 58 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 59 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
www.jahia.com > The Company website
www.jahia.org > The Community website
=
true
Page 60 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)
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 61 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/applicationcontextcustomBeans.xml file)
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 62 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 63 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 highperformance 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 64 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
<!-<Cluster id="clusterNode1">
<Journal class="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>
-->
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}">
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 65 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 66 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:
<!-- You should set jvmRoute to support load-balancing via AJP ie :
<Engine name="Standalone" defaultHost="localhost" jvmRoute="jvm1">
-->
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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 67 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=""/>
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 68 of 91
<entry
<entry
<entry
<entry
<entry
<entry
<entry
<entry
<entry
<entry
<entry
<entry
</map>
</property>
</bean>
•
key="public.bind.password" value=""/>
key="search.attribute" value="cn"/>
key="search.name" value="dc=jahia"/>
key="search.countlimit" value="100"/>
key="search.objectclass" value="groupOfUniqueNames"/>
key="members.attribute" value="uniqueMember"/>
key="dynamic.search.objectclass" value="groupOfURLs"/>
key="dynamic.members.attribute" value="memberurl"/>
key="preload" value="true"/>
key="search.wildcards.attributes" value="cn,description,uniqueMember"/>
key="groupname.attribute.map" value="cn"/>
key="description.attribute.map" value="description"/>
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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 69 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>
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 70 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)?
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 71 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 72 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 73 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 ####################################
######################################################################
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 74 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 75 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 76 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 77 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">
<!-- Set this to debug to activate JAMon monitoring -->
<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:
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 78 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 79 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 80 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 81 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 82 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
www.jahia.com > The Company website
www.jahia.org > The Community website
jahia6_v1 > jahia6_v1.sql
Page 83 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/
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 84 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 85 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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 86 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.

Download the latest hotfix patch from “v6 / download” page and apply it, following the associated
ReadMe.
You are using Jahia v6.0.0 EE (with or without hotfix)
 Download the upgrade patch from 6.0.0 to 6.0.1 from “v6 / download / archive” page and apply it,
following the associated ReadMe.
 Download the upgrade patch from 6.0.1 to 6.1.0 from “v6 / download / archive” page and apply it,
following the associated ReadMe.

Download the latest hotfix patch from “v6 / download” page and apply it, following the associated
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.
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 87 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 88 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:
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 89 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
www.jahia.com > The Company website
www.jahia.org > The Community website
Page 90 of 91
9 route des Jeunes,
CH-1227 Les acacias
Geneva, Switzerland
www.jahia.com
The Company website
www.jahia.org
The Community website