Cet article décrit la mise en place de JCMS 5.5 ou au delà avec Apache 2.0.x (ou 2.2.x) et Tomcat 5.0.x (ou 5.5.x) en utilisant le connecteur JK mod_jk. Si vous souhaitez installer JCMS rapidement, il n'est pas nécessaire d'installer Apache, Tomcat seul suffit car il intègre son propre serveur HTTP. Dans ce cas, consultez l'article Prise en main rapide de JCMS.

1. Architecture

Voici un schéma représentant l'architecture cible :

apache-tomcat_architecture

Architecture d'intégration Apache / mod_jk / JCMS 5.5.

La configuration comprend une seule instance de JCMS. Pour une configuration en haute disponibilité, consultez l'article Mise en oeuvre d’un site JCMS à haute disponibilité avec le protocole de réplication JSync.

2. Pré-requis

Apache httpd 2.0.x
http://httpd.apache.org/
Apache Tomcat JK connector (mod_jk) 1.2.x
http://tomcat.apache.org/connectors-doc/
Apache Tomcat 5.0.x ou Tomcat 5.5.x
http://tomcat.apache.org/
JCMS 5.5 ou au delà
downloads/

3. Installation de JCMS

Téléchargez la version la plus récente de JCMS.

JCMS se présente sous forme d'un fichier WAR (Web ARchive) qui contient une arborescence de fichier compressé au format Zip.

Créez un répertoire "jcms" dans le répertorie C:\jakarta-tomcat-5.0.28\webapps\.

Renommez le fichier téléchargé avec le suffix ".zip" et décompressez le contenu dans le répertoire "jcms".

4. Configuration

4.1 Tomcat

Dans le fichier de configuration de Tomcat (conf/server.xml), on déclare un connecteur AJP qui écoute sur le port 8009, ceci pour que Tomcat reçoive les requêtes AJP en provenance du connecteur mod_jk d'Apache, on s'assure que ce connecteur contient également la directive URIEncoding="UTF-8" :

    <!-- Define a Coyote/JK2 AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" minProcessors="25" maxProcessors="150"
               enableLookups="false" redirectPort="8443" debug="0"
               protocol="AJP/1.3" URIEncoding="UTF-8" />

Il faut également ajouter l'attribute jvmRoute à la balise Engine :

   <Engine name="Catalina" defaultHost="localhost" debug="0" jvmRoute="tomcat1">

Le port et la valeur de l'attribut jvmRoute sont réutilisés dans la configuration d'Apache.

Configuration spécifique pour Tomcat 5.5

Sous unix :

Une modification est nécessaire sous unix pour permettre à JCMS de générer et compiler les classes des types.
Ouvrez me fichier setclasspath.sh qui se trouve dans le repertoire bin de Tomcat. Commentez le bloc if qui entoure l'inclusion de fichier tools.jar, fichier qui est systématiquement requis par JCMS.

Ceci :

# Set standard CLASSPATH
if [ "$1" = "debug" -o "$1" = "javac" ] ; then
  CLASSPATH="$JAVA_HOME"/lib/tools.jar
fi

devient cela :

# Set standard CLASSPATH
#if [ "$1" = "debug" -o "$1" = "javac" ] ; then
  CLASSPATH="$JAVA_HOME"/lib/tools.jar
#fi

Sous Windows :

En mode service, modifiez le class path utilisé par le service Windows. Pour cela, utilisez l'utilitaire graphique disponible dans la barre des tâches de Windows (installé lorsque le mode service est sélectionné). Modifiez le classpath (dans l'onglet Java) pour y ajouter le chemin vers le fichier C:\{jdk_path}\lib\tools.jar, précédé d'un point-virgule (;).

4.2 Apache et mod_jk

4.2.1 Ressources dynamiques (JSP et Servlet)

Créez le fichier workers.properties dans le répertoire conf d'Apache :

worker.list=tomcat1

worker.tomcat1.port=8009
worker.tomcat1.host=localhost
worker.tomcat1.type=ajp13

Dans le fichier de configuration d'Apache (conf/httpd.conf), modifiez la directive DirectoryIndex pour y ajouter des fichiers d'index JSP :

DirectoryIndex index.html index.jsp

A la fin du fichier de configuration d'Apache (conf/httpd.conf), ajoutez la configuration du module JK (mod_jk) :

##################### 
# Tomcat/mod_jk configuration

LoadModule jk_module modules/mod_jk.so

# 1. Configure mod_jk
  
 JkWorkersFile conf/workers.properties
 JkLogFile logs/mod_jk.log
 JkLogLevel info
 JkShmFile logs/shm

# 2. Define resources served by Tomcat
   
 JkMount /jcms/*.jsp       tomcat1
 # Document and archives (for the right filter)
 JkMount /jcms/upload/*    tomcat1
 JkMount /jcms/archives/*  tomcat1
 # Webdav shortcut, Webdav, AJAX & binary download servlet (no ending '/')
 JkMount /jcms/shortcut*   tomcat1
 JkMount /jcms/webdav*     tomcat1
 JkMount /jcms/JSON-RPC*   tomcat1
 JkMount /jcms/BinaryFile* tomcat1

 # From JCMS 5.7 and above, make sure you also include
 # prefix of descriptive URL (default is "jcms")
 JkMount /jcms/jcms* tomcat1

 # From JCMS 6 and above, make sure you also include
 # prefix for JCMS REST Web Services
 JkMount /jcms/rest/* tomcat1

 # To use JCMS Friendly URLs, you must prefix friendly URLs in JCMS
 # with one of the prefix you will below here :
 # JkMount /jcms/someprefix/* tomcat1

# 3. All the other resources are served by Apache

# Prevent access to WEB-INF directory
<Location "/jcms/WEB-INF/">
   AllowOverride None
   deny from all
</Location>

Dans cet exemple, la webapp JCMS est accessible par le chemin de contexte /jcms/. Remplacez /jcms/ par / si votre webapp est accessible par le chemin de contexte racine (/).

Pour traiter les URLs intuitives (Friendly URLs) de JCMS, il faut impérativement préciser dans la configuration du mod_jk un ou plusieurs chemins que vous utiliserez systématiquement comme préfixe des URLs intuitives dans JCMS.
Par exemple, si dans JCMS vous souhaitez avoir une URL intuitive /presse/2006/06/produit, vous devez ajouter la directive JkMount suivante dans le fichier de configuration d'Apache : "JkMount /jcms/presse/* tomcat1".

Vérification intermédiaire du fonctionnement

Dès maintenant, vous pouvez démarrer Tomcat et Apache pour vérifier que les ressources dynamiques sont bien servies.
Le module mod_jk assure la transmission de la requête d'Apache vers Tomcat et la réception de la réponse de Tomcat vers Apache, puis vers votre navigateur.

En accédant à http://localhost/jcms/index.jsp, vous êtes redirigé vers le portail, http://localhost/jcms/display.jsp, les fichiers statiques (css, images, js, ...) n'étant pour l'instant pas encore servit par apache, le portail de JCMS s'affiche sans ceux-ci.

Portail JCMS sans les ressources statiques

Vous obtiendrez une erreur si vous accéder à http://localhost/jcms/. En effet, bien que index.jsp ait été ajouté à la directive DirectoryIndex, Apache n'a pas encore connaissance des fichiers présents dans la webapp. Aucune redirection automatique d'Apache ne peut avoir lieu, pour l'instant.

4.2.2 Fichiers statiques

Pour que Apache puisse servir les fichiers statiques présents dans le repertoire de la webapp JCMS, deux cas se présentent:

La webapp est accessible sur le chemin de contexte racine

Dans le fichier de configuration d'Apache, il faut modifier la directive DocumentRoot et lui indiquer le repertoire de la webapp.

Exemple sur Unix :

DocumentRoot /usr/local/jakarta-tomcat-5.0.28/webapps/ROOT

Exemple sur Windows (notez l'utilisation de "/") :

DocumentRoot "C:/Program Files/Apache/Tomcat 5.0.28/webapps/ROOT"

La webapp est accessible sur un chemin de contexte spécifique

Dans le fichier de configuration d'Apache, il faut ajouter une directive Alias pour faire correspondre le chemin de contexte utilisé au repertoire de la webapp.

Exemple sur Unix, avec le chemin de contexte /jcms/ :

Alias /jcms /usr/local/jakarta-tomcat-5.0.28/webapps/jcms-5.5

Exemple sur Windows, avec le chemin de contexte /jcms/ :

Alias /jcms "C:/Program Files/Apache/Tomcat 5.0.28/webapps/jcms-5.5"

Permissions

Il faut s'assurer que le processus Apache puisse lire les fichiers présents dans le repertoire de Tomcat.

Sous Unix comme sous Windows, la solution la plus simple et la plus sûre consiste à utiliser le même compte utilisateur pour Apache et Tomcat ("System", "apache", "httpd", "www", ...). Pour cela, il faut exécuter Tomcat avec le même compte utilisateur que Apache, en s'assurant que ce compte est le propriétaire des fichiers de Tomcat.

5. Vérification

Pour vérifier que Apache sert bien les fichiers statiques comme attendu, démarrez uniquement Apache;

L'accès aux fichiers statiques fonctionne, essayez par exemple avec :

http://localhost/jcms/css/custom.css
http://localhost/jcms/images/jalios/logos/powered-by-jalios.gif

L'accès aux ressources dynamiques ne fonctionne pas et renvoi une erreur 503 Service Temporarily Unavailable :

http://localhost/jcms/
http://localhost/jcms/index.jsp
Webdav: http://localhost/jcms/webdav/
URLs intuitives : http://localhost/jcms/presse/2006/06/produit

Après le démarrage de Tomcat, l'ensemble de ces liens fonctionnent.

Configurer Apache, mod_jk et Tomcat pour JCMS