Configurer Apache, mod_jk et Tomcat pour JCMS

Cet article décrit la mise en place de JCMS avec Apache et Tomcat 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 :

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
  http://httpd.apache.org/
• Apache Tomcat JK connector (mod_jk)
  http://tomcat.apache.org/connectors-doc/
• Apache Tomcat
  http://tomcat.apache.org/
• JCMS

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:\tomcat\webapps\.

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

Consultez le manuel d'installation et d'exploitation spécifique à votre version de JCMS pour les réglages nécessaire à l'installation de JCMS sur Tomcat. 

4. Configuration

4.1 Principes

Apache est configuré en appliquant le principe suivant :

• toutes les requêtes sont mappées pour être prises en charge vers Tomcat...
• à l'exception des requête explicitement indentifiés comme celles concernant les fichiers statiques 

Cette approche permet d'être indépendant des évolutions de JCMS : si une nouvelle resource dynamique ou protégée fait son apparition dans JCMS (répertoire, filter ou servlet), elle sera automatiquement traitée correctement par le serveur d'application et ne risque pas d'être servie de façon incorrecte par Apache. 
Par conséquent elle permet de garantir une sécurité accrue et reste simple à maintenir.

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

4.3 Apache et mod_jk

4.3.1 Création du worker

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

4.3.2 Activation de mod_jk

Note : sur certaines distributions unix, cette étape pourra simplement être effectué par l'exécution de la commande suivante : 

a2enmod mod_jk

Autrement, éditez le fichier de configuration d'Apache (conf/httpd.conf), puis : 

1. modifiez la directive DirectoryIndex pour y ajouter des fichiers d'index JSP

DirectoryIndex index.html index.jsp

2. ajoutez l'initialisation du module JK (mod_jk)

 LoadModule jk_module modules/mod_jk.so

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

4.3.3 Configuration de mod_jk

Dans fichier de configuration d'Apache (ou dans celui spécifique à votre virtual host), déclarez le mapping :

• des resources dynamiques qui doivent être servies par JCMS, par défaut tout, via un JkMount global sur l'ensemble de la webapp 
• des resources statiques qui doivent être servies par Apache, en excluant explicitement les chemins avec une directive JkUnMount

# 1. Initially map all resources to be served by Tomcat
 JkMount /jcms/       tomcat1
 JkMount /jcms/*      tomcat1

# 2. Then explicitely unmap static resources from tomcat so they get served by Apache
# WARNING : NEVER EVER unmount /upload directory which MUST be served by Tomcat

 JkUnMount /jcms/s.gif         tomcat1
 JkUnMount /jcms/images/*.gif  tomcat1
 JkUnMount /jcms/images/*.jpg  tomcat1
 JkUnMount /jcms/images/*.png  tomcat1
 JkUnMount /jcms/js/*.js       tomcat1
 JkUnMount /jcms/js/*.gif      tomcat1
 JkUnMount /jcms/css/*.css     tomcat1
 JkUnMount /jcms/plugins/*.gif tomcat1
 JkUnMount /jcms/plugins/*.jpg tomcat1
 JkUnMount /jcms/plugins/*.png tomcat1
 JkUnMount /jcms/plugins/*.js  tomcat1
 JkUnMount /jcms/plugins/*.css tomcat1
 JkUnMount /jcms/types/*.gif   tomcat1
 JkUnMount /jcms/types/*.jpg   tomcat1
 JkUnMount /jcms/types/*.png   tomcat1
 JkUnMount /jcms/types/*.js    tomcat1
 JkUnMount /jcms/types/*.css   tomcat1
 JkUnMount /jcms/custom/*.gif  tomcat1
 JkUnMount /jcms/custom/*.jpg  tomcat1
 JkUnMount /jcms/custom/*.png  tomcat1
 JkUnMount /jcms/custom/*.js   tomcat1
 JkUnMount /jcms/custom/*.css  tomcat1

# 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 (/).
A partir de Apache 2.4, la directive deny from all doit être remplacé par Require all denied

4.3.4 Configuration de Apache pour les fichiers statiques

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

Cas 1 : 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/tomcat/webapps/ROOT

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

DocumentRoot "C:/Apache/Tomcat/webapps/ROOT"

Cas 2 : La webapp est accessible sur un chemin de contexte spécifique (e.g.: /jcms/)

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/tomcat/webapps/jcms

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

Alias /jcms "C:/Apache/Tomcat/webapps/jcms"

Important

Si l'ensemble des répertoires gérés par Apache (via une directive "Directory", ou "Location", positionnée sur "/" dans le fichier de configuration) ont été "protégés" par un "Deny from All" (ou l'équivalent  "Require all denied" sur Apache 2.4), il faut alors autoriser explicitement l'accès au répertoire de la webapp, par la directive suivante (exemple pour Unix) :

<Directory "/usr/local/tomcat/webapps/jcms">
    AllowOverride None
    Options None
    Order allow,deny
    Allow from all
</Directory>

Sur Apache 2.4, remplacez les deux directives Order allow,deny et Allow from all par Require all granted

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.

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

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