Compilation & Installation

Author:Thomas Bonfort
Contact:tbonfort at terriscope.fr
Author:Alan Boudreault
Contact:aboudreaut at magears.com
Author:Jeff McKenna
Contact:jmckenna at gatewaygeomatics.com
Author:Mathieu Coudert
Contact:mathieu.coudert at gmail.com
Last Updated:2016-02-02

Obtenir les sources

Le projet MapCache est situé sur https://github.com/mapserver/mapcache, et peut être récupéré avec soit:

# readonly
git clone git://github.com/mapserver/mapcache.git
# ssh authenticated
git clone git@github.com:mapserver/mapcache.git
# tarball
wget https://github.com/mapserver/mapcache/zipball/master

Instructions Linux

Ces instructions ciblent une mise en place sous Debian/Ubuntu, mais devraient s’appliquer avec quelques modifications à n’importe quelle installation Linux.

MapCache nécessite un certain nombre d’en-têtes de bibliothèques pour pouvoir être compilé correctement:

  • apache / apr / apr-util / apx2: ceux-ci sont inclus dans les paquets apache2-prefork-dev ou apache2-threaded-dev, en fonction du MPM (Multi-Processing Module) Apache que vous faites tourner. Ce paquet récupérera les en-têtes APR nécessaires, que vous auriez normalement installé manuellement si vous n’aviez pas compilé un module Apache (libaprutil1-dev et libapr1-dev)
  • png: libpng12-dev
  • jpeg: libjpeg62-dev
  • curl: libcurl4-gnutls-dev

Les bibliothèques suivantes ne sont pas requises mais sont néanmoins recommandées:

  • pcre: libpcre3-dev. Ceci vous offrira une syntaxe d’expression régulière plus puissante lors de la création de motifs de validation pour les dimensions
  • pixman: libpixman-1-dev. La bibliothèque de manipulation de pixel est utilisée pour la mise à l’échelle et la composition alpha des images. MapCache intègre des portions de code pour réaliser ces tâches, mais Pixman est généralement plus rapide car il possède un code optimisé pour les microprocesseurs modernes (SSE2, MMX etc.)

Les librairies suivantes ne sont pas indispensables, mais nécessaires pour activer des fonctionnalités additionnelles:

  • fcgi: libfcgi-dev. Utilisé pour compiler une version FastCGI si vous ne voulez pas utiliser MapCache en module Apache.
  • gdal / geos: libgdal1-dev libgeos-dev. Nécessaires pour activer les options avancées de génération de cache (pour ne générer que les tuiles qui intersecte un objet géographique donné)
  • sqlite: libsqlite3-dev. Pour permettre l’utilisation de SQLite pour le stockage des tuiles.
  • tiff: libtiff4-dev. Pour permettre l’utilisation de fichiers TIFF pour le stockage des tuiles.
  • berkeley db libdb4.8-dev : Pour permettre l’utilisation de Berkeley DB pour le stockage des tuiles.

Note

MapCache se compile désormais avec CMake.

Pour les utilisateurs UNIX dont tous les paquetages sont dans les emplacements par défaut, la compilation devrait se résumer à:

$ cd mapcache
$ mkdir build
$ cd build
$ cmake ..
$ # follow instructions below if missing a dependency
$ make
$ sudo make install

Instructions spécifiques au module Apache

Le make install ci-dessus installe le module Apache, mais si vous devez spécifiquement n’installer que le module Apache, vous pouvez faire ce qui suit

$ sudo make install-module
$ sudo ldconfig

Le script d’installation fait en sorte de déposer le module compilé dans le répertoire apache des modules. Les modalités d’activation des modules sont généralement spécifiques aux distributions utilisées, mais peut se résumer à l’extrait suivant qui devrait être présent dans la configuration Apache ( e.g. /usr/local/httpd/conf/httpd.conf ou /etc/apache2/sites-available/default ):

LoadModule mapcache_module    modules/mod_mapcache.so

Ensuite, une configuration mapcache est associée à l’URL du serveur par l’extrait suivant

Pour Apache < 2.4:

<IfModule mapcache_module>
   <Directory /path/to/directory>
      Order Allow,Deny
      Allow from all
   </Directory>
   MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
</IfModule>

Pour Apache >= 2.4:

<IfModule mapcache_module>
   <Directory /path/to/directory>
      Require all granted
   </Directory>
   MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
</IfModule>

Avant de redémarrer, copiez le fichier d’exemple mapcache.xml à l’emplacement spécifié dans votre configuration Apache:

$ cp mapcache.xml /path/to/directory/mapcache.xml

Enfin, redémarrer Apache pour activer la nouvelle configuration

$ sudo apachectl restart

Si vous n’avez pas désactivé le service de démonstration, vous devriez pouvoir y accéder à l’adresse http://myserver/mapcache/demo

Instructions spécifiques Nginx

Avertissement

Travailler avec nginx est toujours en quelque sorte expérimental. Le processus suivant a uniquement été testé sur la version de développement, soit nginx-1.1.x

Pour le support nginx vous devez compiler mapcache avec les sources de nginx. Télécharger le code source de Nginx:

$ cd /usr/local/src
$ mkdir nginx
$ cd nginx
$ wget http://nginx.org/download/nginx-1.1.19.tar.gz
$ tar -xzvf nginx-1.1.19.tar.gz
$ cd nginx-1.1.19/

Lancez la commande de configure avec l’option --add-module. Cette option doit pointer vers le répertoire nginx de mapcache. En partant du principe que les sources de MapServer on été clonées ou décompressées dans /usr/local/src, un exemple d’instruction configure pour nginx ressemblerait à ceci:

$ ./configure --add-module=/usr/local/src/mapcache/nginx

Ensuite compiler nginx:

$ make
$ sudo make install

Du fait de l’architecture non-bloquante de Nginx, le module nginx de MapCache ne réalise aucune opération qui pourrait déboucher sur un blocage du process en cours par un calcul trop long (i.e : requêter une (meta)tuile absente du cache, proxyfier une requête vers un serveur WMS distant ou attendre qu’une tuile soit rendue par un autre process). Il génère alors une erreur 404. Ce comportement est essentiel pour que tous les process nginx ne soient occupés et ne l’empêchent de répondre à d’autres requêtes. Alors que cela ne pose pas de problème pour les jeux de tuiles complètement générés, ceci implique que ce genre de requêtes doivent être proxyfiées vers une autre instance de MapCache ne souffrant pas de ces problèmes d’alimentation (i.e. soit un MapCache cgi, soit un serveur apache proxyfié). Dans ce scénario, les deux instances nginx et apache/fastcgi de MapCache doivent partager le même fichier de configuration mapcache.xml.

MapCache fournit un ficheir nginx.conf dans son sous-répertoire nginx. Ce fichier contient un exemple de configuration pour charger MapCache. La partie la plus importante de la configuration est la directive location qui associe l’URI ^/mapcache au chemin vers mapcache.xml. Vous devrez adapter cette directive afin qu’elle désigne votre propre fichier mapcache.xml

La configuration de base sans aucun mandataire (qui renverra des erreurs 404 sur les tuiles inexistantes) est :

location ~ ^/mapcache(?<path_info>/.*|$) {
   set $url_prefix "/mapcache";
   mapcache /usr/local/src/mapcache/mapcache.xml;
}

Lors de la proxyfication des requêtes sur les tuiles inexistantes vers une instance de MapCache tournant sur un serveur Apache, nous renverrons toutes les erreurs 404 de MapCache vers un serveur mapcache.apache.tld associé au port 8080, configuré pour répondre aux requêtes sur l’emplacement /mapcache.

location ~ ^/mapcache(?<path_info>/.*|$) {
   set $url_prefix "/mapcache";
   mapcache /usr/local/src/mapcache/mapcache.xml;
   error_page 404 = @apache_mapcache;
}

location @apache_mapcache {
   proxy_pass http://mapcache.apache.tld:8080;
}

Si vous utilisez des instances FastCGI de MapCache, générées par par exemple spawn-fcgi ou supervisord sur le port 9001 (prenez soin d’activer le support FastCGI lors de la compilation de MapCache et de régler la variable d’environnement MAPCACHE_CONFIG_FILE avant la génération) :

location ~ ^/mapcache(?<path_info>/.*|$) {
   set $url_prefix "/mapcache";
   mapcache /usr/local/src/mapcache/mapcache.xml;
   error_page 404 = @fastcgi_mapcache;
}

location @fastcgi_mapcache {
   fastcgi_pass   localhost:9001;
   fastcgi_param  QUERY_STRING     $query_string;
   fastcgi_param  REQUEST_METHOD   $request_method;
   fastcgi_param  CONTENT_TYPE     $content_type;
   fastcgi_param  CONTENT_LENGTH   $content_length;
   fastcgi_param  PATH_INFO        $path_info;
   fastcgi_param  SERVER_NAME      $server_name;
   fastcgi_param  SERVER_PORT      $server_port;
   fastcgi_param  SCRIPT_NAME      "/mapcache";
}

Copier les sections correspondantes de nginx.conf du répertoire nginx de MapCache dans le fichier de configuration de Nginx (dans notre cas /usr/local/nginx/conf/nginx.conf). Vous devriez alors avoir accès à la demo à l’URL http://myserver/mapcache/demo

Instructions spécifiques CGI/FastCGI

Un binaire cgi/FastCGI est situé dans le sous-répertoire MapCache, et est nommé « mapcache ». L’activation du FastCGI pour le programme MapCache sur votre serveur web ne fait pas partie de ces instructions. Plus de détails peuvent être trouvés à la page :ref:`FastCGI <fastcgi>`ou dans ces pages web plus générale sur Internet.

La programme MapCache FastCGI recherche son fichier de configuration dans la variable d’environnement MAPCACHE_CONFIG_FILE, qui doit donc être paramétrée par le serveur web avant qu’il ne génère des process MapCache.

Pour Apache avec mod_cgi:

SetEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml"

Pour Apache avec mod_fcgid:

FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml

Si vous n’avez pas désactivé le service de démonstration, vous devriez maintenant pouvoir y accéder à l’URL http://myserver/fcgi-bin/mapcache/demo pour peu que vos process fcgi soient accessibles par l’alias fcgi-bin.

Avec une instance Apache fonctionnant avec mod_fcgid, la partie à ajouter à httpd.conf pour activer mapcache pourrait être :

<IfModule mod_fcgid.c>
   IPCCommTimeout 120
   MaxProcessCount 10
   FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml"
   <Location /map.fcgi>
      Order Allow,Deny
      Allow from all
      SetHandler fcgid-script
   </Location>
   ScriptAlias /map.fcgi "/path/to/mapcache/src/mapcache"
</IfModule>

Le service MapCache sera alors accessible à l’URL http://myserver/map.fcgi[/demo]

Personnaliser la compilation, ou s’il y a eu un problème

Selon les paquetages disponibles dans les emplacement par défaut de votre système, l’étape « cmake .. » se sera probablement interrompue avec des messages indiquant des dépendances manquantes (par défaut, MapCache en a plusieurs). Le message d’erreur indiqué par MapCache devrait vous donner de bons indices quant à ce qu’il vous reste à faire, selon que la dépendance manquante vous est nécessaire ou pas.

mod_mapcache nécessite les en-têtes de développement Apache, libcurl, libjpeg et libpng. Le script CMake tentera de les localiser dans les emplacements par défaut du système, qui peut être outrepassé avec des commutateurs -D. Par exemple, si vous avez un message tel que “Could not find APR”, vous pouvez utiliser une commande telle que (en supposant que apr est dans /usr/local/apr):

$ cmake -DCMAKE_PREFIX_PATH="/usr/local/apr;" ..

De même si vous ne voulez pas de fCGI, vous pouvez désactiver la dépendance en relançant le cmake avec -DWITH_DEPENDENCY=0, e.g.

$ cmake .. -DWITH_FCGI=0

Options supportées par le compilateur cmake MapCache

Voici une liste des options supportées qui peuvent être activées/désactivées à la compilation.

option(WITH_PIXMAN "Use Pixman for SSE optimized image manipulations" ON)
option(WITH_SQLITE "Use SQLite as a cache backend" ON)
option(WITH_BERKELEY_DB "Use Berkeley DB as a cache backend" OFF)
option(WITH_MEMCACHE "Use memcache as a cache backend (requires recent apr-util)" OFF)
option(WITH_TIFF "Use TIFFs as a cache backend" OFF)
option(WITH_TIFF_WRITE_SUPPORT "Enable (experimental) support for writable TIFF cache backends" OFF)
option(WITH_GEOTIFF "Allow GeoTIFF metadata creation for TIFF cache backends" OFF)
option(WITH_PCRE "Use PCRE for regex tests" OFF)
option(WITH_MAPSERVER "Enable (experimental) support for the MapServer library" OFF)
option(WITH_GEOS "Choose whether GEOS geometry operations support should be built in" ON)
option(WITH_OGR "Choose whether OGR/GDAL input vector support should be built in" ON)
option(WITH_CGI "Choose whether CGI executable should be built" ON)
option(WITH_FCGI "Choose whether CGI executable should support FastCGI" ON)
option(WITH_VERSION_STRING "Show MapCache in server version string" ON)
option(WITH_APACHE "Build Apache Module" ON)
  • Pixman (recommandé, à partir de la version 0.5)

    -DWITH_PIXMAN=[0|1]
    

    Pixman est une bibliothèque de manipulation de pixel utilisée pour assembler les tuiles lors des réponses à des requêtes WMS non tuilées. Le recours à Pixman est recommandé dans la mesure où il est parfaitement optimisé et tirera parti des récentes extensions des microprocesseurs (MMX, SSE…) pour accélérer les opérations de remplissage et de ré-échantillonnage. Si la bibliothèque Pixman n’est pas trouvée, MapCache utilisera son mécanisme interne qui est plus lent.

  • SQLite (optionnel, à partir de la version 0.5)

    -DWITH_SQLITE=[0|1]
    

    SQLite est utilisé pour permettre d’avoir les caches backend de type SQLite et MBTiles. La version 3.5.0 ou plus récente est requise.

  • GDAL (optionnel, à partir de la version 0.4, nécessite aussi la bibliothèque geos)

    -DWITH_OGR=[0|1]
    

    GDAL (ou plutôt OGR) est utilisé par le pré-générateur de cache pour permettre la génération de tuiles intersectant un polygone donné, pour par exemple pré-générer les tuiles sur un pays particulier.

  • GEOS (optionnel, à partir de la version 0.5)

    -DWITH_GEOS=[0|1]
    

    Parallèlement à GDAL/OGR, GEOS est requis par le pré-générateur pour tester les intersection des tuiles avec des entités géographiques. Une version suffisamment récente de GEOS (avec la prise en charge des géométries préparées) est nécessaire (mais pas vérifié par le script de configuration, vous pouvez donc avoir des erreurs à la compilation avec une version trop ancienne de GEOS)

  • PCRE (optionnel)

    -DWITH_PCRE=[0|1]
    

    Les PCRE (perl compatible regular expressions) peuvent être utilisées en remplacement des expressions régulières POSIX pour valider les dimensions WMS. Elles sont plus puissantes que les expressions régulières POSIX (et peuvent être plus lentes). Vous n’avez pas besoin de ce composant si vous n’avez pas l’intention d’utiliser les dimensions WMS avec un validateur d’expression régulière, ou si vos besoins sont couverts par POSIX.

  • Support FastCGI (optionnel)

    -DWITH_FCGI=[0|1]
    

    MapCache peut fonctionner comme un exécutable FastCGI. Notez bien que la charge induite par FastCGI n’est pas négligeable comparativement aux résultats que vous pourriez obtenir avec un module Apache natif. La version FastCGI est moins testée et peut être à la traîne de la version module Apache sur quelques détails mineurs.

  • **Support du cache TIFF en lecture/écriture ** (optionnel)

    Utiliser des fichiers TIFFs comme système de stockage du cache (LECTURE SEULE)

    -DWITH_TIFF=[0|1]
    

    Le support du TIFF en écriture (pour créer de nouveaux fichiers TIFF et ajouter des tuiles à des fichiers TIFF existants) est toujours expérimental et désactivé par défaut. Il y a un risque à obtenir des fichiers TIFF corrompus s’ils ne sont pas placés sur un système de fichiers qui ne permet pas le verrouillage de fichier, car dans ce cas de multiples processus pourraient venir écrire dans le même fichier. Le blocage de fichier entre des processus concurrents est également problématique, bien que MapCache essaie de détecter cette situation en amont et de l’éviter. Pour rester prudent, le mode écriture ne devrait être activé que sur des systèmes de fichiers locaux, avec un Apache prefork ou une installation de MapCache en fastCGI.

    -DWITH_TIFF_WRITE_SUPPORT=[0|1]
    

    Lors de l’écriture de fichiers TIFF, MapCache peut également ajouter des informations de géoréférencement s’il a été compulé avec le support libtiff. L’écriture de GeoTIFF ne génère pas les informations nécessaires au référencement de la projection de la grille, mais seulement l’échelle du pixel et les points de calage (comme on le retrouve dans les fichiers .tfw)

    -DWITH_GEOTIFF=[0|1]
    

    Voir aussi

    Caches (Geo)TIFF

  • **Support du cache de type Memcached ** (optionnel)

    -DWITH_MEMCACHE=[0|1]
    

    Le système de cache memcached est désactivé par défaut. Vous pouvez optionnellement l’activer car il ne dépend pas de bibliothèques extérieures (c’est apr-util qui le fournit).

    Voir aussi

    Caches Memcache

  • Options de module Apache

    Vous pouvez désactiver la compilation du module Apache si vous prévoyez uniquement d’utiliser l’exécutable FastCGI ou le pré-générateur.

    -DWITH_APACHE=[0|1]
    

    MapCache se rajoute à l’information de version rapportée par le serveur Apache. Ceci peut être désactivé avec

    -DWITH_VERSION_STRING=[0|1]
    
  • Mode MapServer natif (options expérimentales)

    Par défaut MapCache n’est pas lié à MapServer en aucune sorte, et communique uniquement via le protocole WMS. Pour des raisons de performances, il y a la possibilité d’utiliser directement la bibliothèque C de MapServer et éviter ainsi une requête HTTP et une compression/décompression d’image. Cette intégration est néanmoins expérimentale et doit être utilisée avec précaution.

    -DWITH_MAPSERVER=[0|1]
    

    Ceci utilisera le libmapserver.so du répertoire d’installation de MapServer. MapServer lui-même devra avoir été compilé avec l’option thread_safety activée, à moins que vous n’utilisiez qu’apache en mode prefork ou FastCGI, et que vous n’envisagiez pas l’utilisation du pré-générateur. Pour le thread-safety côté MapServer, voyez les tickets #4041 et #4044.

  • Mode Debug (travail en cours)

    Note

    Depuis la migration vers CMake, cela doit être fait.

    Ceci active quelques tests complémentaires dans le code et génère beaucoup plus de messages de debug dans le log serveur. Vous ne devriez probablement pas l’activer à moins de vouloir traquer un problème au sein de MapCache.

Instructions Windows

Avertissement

Les instructions suivantes sont périmées, les compilations Windows sont maintenant traitées de manière identique à celle sous Unix avec cmake.

Ces instructions s’adressent à une configuration Windows 7 avec un Apache httpd compilé à partir des sources. Le module Apache MapCache a été compilé avec succès avec Microsoft Visual Studio C++ versions 2003, 2008 and 2010.

Dépendances

Requis:

  • Apache / APR / APR-UTIL: inclus avec l’installation httpd Apache

Celles-ci peuvent être installées manuellement ou en utilisant le SDK Windows prévu à cet effet depuis http://vbkto.dyndns.org/sdk/

  • PNG
  • JPEG
  • CURL

Recommandé:

Optionnel:

  • FCGI: Nécessaire à la compilation du programme FastCGI si vous ne voulez par faire tourner MapCache en tant que module Apache.
  • GDAL / GEOS:: nécessaires à l’activation des options avancées du pré-générateur (pour ne générer que les tuiles intersectant une entité géographique quelconque)
  • SQLITE: Pour activer le stockage dans SQLite
  • TIFF: Pour activer le stockage dans des fichiers TIFF

Configurer votre Makefile

Ouvrez nmake.opt et modifiez les chemins vers les diverses bibliothèques.

Compilation

$ nmake /f Makefile.vc

En cas de succès, les biliothèques et exécutables auront été générés dans leurs répertoires respectifs:

apache/
Module Apache (mod_mapcache.dll)
cgi/
Exécutable MapCache FastCGI (mapcache.exe)
util/
Utilitaires MapCache (mapcache_seed.exe)

Déplacer le module dans le répertoire Apache

Copiez le fichier mod_mapcache.dll dans un de vos sous-répertoires Apache.

Note

Bien que les autres modules soient installés dans /Apache/modules/, vous devriez placer mod_mapcache.dll là où sont ses fichiers dll associés (libcurl.dll, zlib.dll, etc.) afin d’éviter tout problème ultérieur de chargement.

Configurer votre Apache installé

  • Modifier votre fichier httpd.conf pour charger le module:

    LoadModule mapcache_module "D:/ms4w/Apache/cgi-bin/mod_mapcache.dll"
    
  • Ensuite, configurez votre répertoire MapCache avec le contenu suivant

    <IfModule mapcache_module>
       <Directory "D:/ms4w/apps/mapcache/">
          Order Allow,Deny
          Allow from all
       </Directory>
       MapCacheAlias /mapcache "D:/ms4w/apps/mapcache/mapcache.xml"
    </IfModule>
    
  • Configurez votre fichier mapcache.xml (voir la section Configuration)

    Avertissement

    Si vous obtenez une erreur telle que « cache disk: host system does not support file symbolic linking », vous devriez commenter la ligne « <symlink_blank/> » dans votre fichier mapcache.xml, ainsi :

    <cache name="disk" type="disk">
      <base>D:/ms4w/tmp/ms_tmp/cache</base>
      <!--<symlink_blank/>-->
    </cache>
    
  • Enfin, redémarrer votre Apache. Vous devriez voir un message dans l’error.log d’Apache similaire à:

    [notice] Apache/2.2.21 (Win32) mod-mapcache/0.5-dev configured -- resuming normal operations
    

Tester votre module MapCache

  • Dans votre navigateur web, allez à la page locale de démonstration MapCache http://127.0.0.1/mapcache/demo/. Vous devriez vois apparaître une liste cliquable de lien de démonstration:

    tms
    wmts
    gmaps
    kml
    ve
    wms
    
  • Cliquez sur l’une des démonstration (http://127.0.0.1/mapcache/demo/wmts par exemple), un visualiseur cartographique devrait apparaître, similaire à l’image ci-dessous:

    ../_images/mapcache-demo.jpg
  • Zoomez plusieurs fois, et votre emplacement de cache devrait générer des tuiles (dans notre cas dans :/ms4w/tmp/ms_tmp/cache/).

    ../_images/mapcache-disk.jpg