Migrer un GeoServer v2.16 vers v3.0 dockerisé : pourquoi et comment procéder version par version

Introduction

#

Il y a des serveurs qu’on n’ose plus toucher. Le nôtre était de ceux-là : une instance GeoServer v2.16.4 (millésime 2019), installée en baremetal — un Jetty posé directement sur la VM — sur le serveur de production de la plateforme Géo, hébergé chez Business Geografic. Elle sert des dizaines de couches raster, dont des dalles ECW, et n’a pas bougé depuis des années. Le genre de configuration qui fonctionne… jusqu’au jour où il faut la déplacer.

Ce jour est arrivé. Dans la nouvelle infrastructure géomatique que nous préparons, GeoServer tournera sous Docker, en version v3.0.0. Impossible de recopier bêtement l’ancien répertoire de configuration : entre v2.16 et v3.0, il y a six ans, douze versions mineures, un changement de runtime Java et une rupture de namespace servlet (javax → jakarta). Un saut direct n’est ni testé ni fiable.

Table des matières

#

• Le point de départ et la cible
• Pourquoi une migration « en escalier »
• Les deux contraintes qui dictent l’architecture
• La matrice des paliers
• L’outillage : trois briques Docker
• La procédure pas à pas
• Points de vigilance par version
• La validation, pour de vrai
• Servir la v3.0.0 derrière un reverse-proxy
• Conclusion

Le point de départ et la cible

#

D’un côté, la production actuelle : GeoServer v2.16.4, Jetty installé à même la VM, chez l’hébergeur historique. De l’autre, la cible : GeoServer v3.0.0 dans un conteneur Docker, sur la futur infrastructure GEOen cours de déploiement, avec le rendu ECW natif assuré par GDAL (et non par une extension GeoServer).

graph LR
    subgraph PROD["Production actuelle — Business Geografic"]
        A["GeoServer v2.16.4
Jetty baremetal
`data dir` 2019"]
    end
    subgraph CIBLE["Cible — vca-infra-geo"]
        B["GeoServer v3.0.0
Docker + ECW natif
Jakarta / Jetty 12"]
    end
    A -->|"migration du `data dir`"| B
    style A fill:#ffe0b2,stroke:#e65100,stroke-width:2px,color:#000
    style B fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000

Ce qui voyage entre les deux, ce n’est pas le binaire GeoServer : c’est le data dir, le répertoire de configuration qui contient workspaces, stores, couches, styles et paramètres de sécurité. C’est lui, et lui seul, qu’il faut faire évoluer proprement.

Le nôtre a un profil bien précis, relevé à l’inspection.

Pourquoi une migration « en escalier »

#

Le point clé à comprendre : GeoServer applique ses migrations de data dir au démarrage. Quand une version boote sur un répertoire écrit par une version antérieure, elle le met à niveau — réécriture de la configuration de logging, du répertoire de sécurité, des quotas, etc. Ces migrations sont écrites pour passer d’une version à la suivante, pas pour rattraper six ans d’un coup.

Faire booter directement la v3.0 sur un data dir v2.16, c’est demander à un seul démarrage d’appliquer une douzaine de transformations qui n’ont jamais été testées enchaînées. La méthode fiable consiste à faire charger le même data dir par chaque version mineure successive, dans l’ordre — c’est l’escalier :

graph LR
    S["v2.16.4
(source)"] --> V17["v2.17.5"] --> V18["v2.18.7"] --> Vdots["…"] --> V27["v2.27.5"] --> V28["v2.28.4"] --> V30["v3.0.0"]
    style S fill:#ffe0b2,stroke:#e65100,stroke-width:2px,color:#000
    style V30 fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000

Chaque marche applique ses migrations de boot, puis passe le témoin à la suivante. Inutile de rejouer la v2.16 elle-même : le data dir existe déjà dans cette version, on démarre donc l’escalier à la v2.17.

Les deux contraintes qui dictent l’architecture

#

Si la méthode « en escalier » était le seul enjeu, on enchaînerait treize docker run avec la même image. Mais deux ruptures techniques traversent la plage v2.16 → v3.0 et imposent deux tiers d’images différentes.

Contrainte 1 — le runtime Java

#

GeoServer v2.16 tourne sur Java 8/11. Les versions v2.28+ et v3.0 exigent Java 17 minimum. Impossible donc d’utiliser un seul runtime Java pour tout l’escalier.

Quelle version couvre la plus grande plage ? La documentation officielle donne la réponse : Java 11 est le seul dénominateur commun du tier ancien.

Java 8 ne monte pas jusqu’à la v2.25 ; Java 17 ne descend pas jusqu’à la v2.16. La v2.27 est la dernière version compatible Java 11, et c’est la v2.28 qui impose Java 17. La bascule de tier tombe donc pile entre ces deux marches.

Le variant Java se gère dans l’image de base gdal-ecw

#

Nos images GeoServer ne partent pas d’une base neutre : elles héritent de l’image docker préalablement construite à cet effet que le ‘on retrouve ici :

C’est une image maison qui embarque GDAL et le SDK ECW/Hexagon (c’est elle qui apporte le rendu raster natif). C’est donc elle qui doit fournir le bon runtime Java — et il a fallu la faire évoluer pour produire, au choix, du Java 11 ou du Java 21 depuis un seul Dockerfile, piloté par un build-arg JAVA_VERSION.

Le hic : l’image repose sur Debian 13 (Trixie), qui ne package plus openjdk-11 (la série OpenJDK Debian est passée à 17 en Bookworm, 21/25 en Trixie). Un docker build --build-arg JAVA_VERSION=11 échouait sur Package 'openjdk-11-jre-headless' has no installation candidate. Le correctif consiste à basculer sur Eclipse Temurin 11 (Adoptium) uniquement pour ce variant :

# gdal-ecw-docker/Dockerfile — sélection du runtime selon JAVA_VERSION
RUN if [ "$JAVA_VERSION" = "11" ]; then \
        # Debian Trixie n'a plus openjdk-11 -> Temurin 11 depuis le dépôt Adoptium
        curl -fsSL https://packages.adoptium.net/artifactory/api/gpg/key/public \
            | gpg --dearmor > /etc/apt/keyrings/adoptium.gpg; \
        echo "deb [signed-by=/etc/apt/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb \
             $(. /etc/os-release; echo $VERSION_CODENAME) main" > /etc/apt/sources.list.d/adoptium.list; \
        apt-get update && apt-get install -y --no-install-recommends temurin-11-jre; \
        ln -sfn /usr/lib/jvm/temurin-11-jre-amd64 /usr/lib/jvm/gdal-java; \
    else \
        # 17/21/25 : OpenJDK Debian standard
        apt-get install -y --no-install-recommends openjdk-$JAVA_VERSION-jre-headless; \
        ln -sfn /usr/lib/jvm/java-$JAVA_VERSION-openjdk-amd64 /usr/lib/jvm/gdal-java; \
    fi
ENV JAVA_HOME=/usr/lib/jvm/gdal-java

L’astuce qui rend le reste de la chaîne indifférente au fournisseur : un symlink stable /usr/lib/jvm/gdal-java, pointé sur Temurin ou l’OpenJDK selon le cas, et exposé via JAVA_HOME. Le LD_LIBRARY_PATH (qui doit inclure $JAVA_HOME/lib pour que libgdalalljni.so trouve la JVM) et les images GeoServer en aval n’ont ainsi rien à savoir du fournisseur Java réel.

Contrainte 2 — le namespace servlet et Jetty

#

Deuxième rupture, plus profonde : GeoServer v3.0 abandonne javax.servlet pour Jakarta Servlet 6.1 (Jakarta EE 11). Ce n’est pas un détail cosmétique : cela change les modules de déploiement du serveur d’applications.

• Le tier ancien (v2.x, javax.servlet) tourne sur Jetty 10 (compatible Java 11).
• La v2.28 reste en javax mais exige Java 17+ : on la sert avec Jetty 12 en modules de compatibilité EE8 (ee8-*).
• La v3.0 en Jakarta EE11 exige les modules ee11-*, disponibles seulement à partir de Jetty 12.1 — d’où l’exigence de cette version précise.

C’est le croisement de ces deux contraintes qui dessine les deux tiers :

graph TB
    subgraph T1["allfab/gdal-ecw:java11"]
        direction LR
        A["v2.17 → v2.27
Java 11 · Jetty 10
profil jetty10-javax"]
    end
    subgraph T2["allfab/gdal-ecw:latest"]
        direction LR
        B["v2.28
Java 21 · Jetty 12.1
profil jetty12-ee8"]
        C["v3.0.0
Java 21 · Jetty 12.1
profil jetty12-ee11"]
    end
    A --> B --> C
    style A fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
    style B fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#000
    style C fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000

La matrice des paliers

#

En combinant tout, on obtient treize marches. Elle est définie dans le tableau STEPS de migrate.sh — la source de vérité de l’escalier.

L’outillage : trois briques Docker

#

Pour rendre cet escalier reproductible, trois pièces travaillent ensemble.

Un Dockerfile paramétré

#

Une seule recette d’image, généralisée par build-args, produit n’importe quelle marche :

# Chaque palier se construit à partir des mêmes build-args
ARG BASE_IMAGE=allfab/gdal-ecw:latest   # :java11 (tier ancien) ou :latest (tier récent)
ARG GS_VERSION                          # version GeoServer du palier, ex. v2.24.5
ARG JETTY_VERSION                       # 10.0.24 (Java 11) ou 12.1.7 (Java 21)
ARG SERVLET_PROFILE                     # jetty10-javax | jetty12-ee8 | jetty12-ee11
# JAVA_HOME et GDAL_VERSION sont HÉRITÉS de l'ENV de la base -> suivent le variant

Le point important : JAVA_HOME et GDAL_VERSION ne sont plus figés dans le Dockerfile mais hérités de l’image de base. Ils suivent donc automatiquement le variant Java 11 ou Java 21, sans intervention.

Un startup.sh qui choisit les modules Jetty

#

Au démarrage, le script d’entrée sélectionne les modules de déploiement selon le profil servlet :

case "${SERVLET_PROFILE}" in
  jetty10-javax) DEPLOY_MODULES="deploy,jsp" ;;          # Jetty 10, javax (GeoServer v2.x)
  jetty12-ee11)  DEPLOY_MODULES="ee11-deploy,ee11-jsp" ;; # Jetty 12.1, Jakarta EE11 (GeoServer v3.0)
  jetty12-ee10)  DEPLOY_MODULES="ee10-deploy,ee10-jsp" ;; # repli EE10
  *)             DEPLOY_MODULES="ee8-deploy,ee8-jsp" ;;   # Jetty 12, javax EE8 (GeoServer v2.28)
esac

Un orchestrateur migrate.sh

#

C’est le chef d’orchestre du staircase. Pour chaque palier, il enchaîne quatre opérations :

flowchart TD
    A["Snapshot de l'état d'entrée
migration/steps/nn-gs/"] --> B["Lancement du conteneur
sur migration/work/config"]
    B --> C{"HTTP 200 sur
/geoserver/web/ ?"}
    C -->|"non, timeout"| E["Échec → log + arrêt"]
    C -->|"oui"| D["Pause de flush
puis arrêt gracieux"]
    D --> F["Palier suivant"]
    style A fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px,color:#000
    style D fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
    style E fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000

Chaque étape est journalisée dans migration/logs/<nn>-<gs>.log, avec un décompte des ERROR/WARN. Et pour les essais manuels, un docker-compose.migration.yml permet de rejouer un seul palier avec un healthcheck.

La procédure pas à pas

#

1. Construire le variant de base Java 11

#

Depuis le dépôt gdal-ecw-docker :

docker build --build-arg JAVA_VERSION=11 -t allfab/gdal-ecw:java11 .

2. Récupérer le data dir de production

#

# Sauvegarde de référence, jamais modifiée
mkdir -p ~/downloads/geoserver-2.16.4 \
  && scp -r prod:/opt/data/geoserver/data-config ~/downloads/geoserver-2.16.4/

# Copie source dans le projet (racine du `data dir` = migration/src/config)
cp -a ~/downloads/geoserver-2.16.4/data-config ./migration/src/config
sudo chown -R 1000:1000 ./migration/src/config   # user jetty (UID/GID 1000)

3. Lancer la migration complète

#

Depuis le dépôt geoserver-ecw-dockerr :

# construit chaque image de palier puis la joue (v2.17.5 -> v3.0.0)
BUILD=1 ./migrate.sh

# reprise à un palier précis (1-based), sur la copie de travail existante :
START_STEP=8 ./migrate.sh

Points de vigilance par version

#

Douze versions, ce sont douze occasions de surprises. La bonne nouvelle : sur notre data dir, aucune n’empêche le démarrage. Les ruptures listées ci-dessous concernent surtout le service en production et se traitent sur l’image finale v3.0.0.

Les deux pièges les plus sournois sont liés, et concernent tous deux la sonde de démarrage — celle qui décide si un palier a réussi à booter. Ils se cumulent en deux temps :

1. v2.21 — le CryptoMapper Wicket est activé : /geoserver/web/ ne répond plus 200 directement, mais 302 vers une URL chiffrée (?wicket-crypt=…). Une sonde qui n’accepterait que le 200 conclurait à tort à un échec. Correctif : suivre la redirection (curl -L).
2. v2.24 — le JSESSIONID devient HttpOnly et obligatoire sur cette URL chiffrée. Suivre la redirection ne suffit plus : sans renvoi du cookie de session, la 302 reboucle en boucle (≈ 50 fois) jusqu’au timeout. Correctif : activer un moteur de cookies en mémoire (curl -b /dev/null).

La validation, pour de vrai

#

Atteindre la v3.0.0 sans erreur au boot, c’est nécessaire mais pas suffisant : cela prouve que le data dir se charge, pas encore qu’il rend. Le vrai test, c’est un GetMap ECW sur les vraies données de production.

Premier obstacle : le data dir ne contient que la configuration, pas les dalles raster. Il a fallu rapatrier les ~41 Go de rasters (ECW, JP2ECW, GeoTIFF), stockés à un emplacement distinct du data dir :

scp -r prod:/opt/data/geoserver/data-src ./migration/src/data
sudo chown -R 1000:1000 ./migration/src/data

Second obstacle, plus sournois : les coverageStore.xml référencent les fichiers par des chemins absolus de production.

<url>file:///opt/data/geoserver/data-src/raster/ortho/scot_2023/vca_scot_ortho_2023.ecw</url>

Réécrire ~130 fichiers XML pour les repointer aurait été fastidieux et risqué. La parade est bien plus simple : monter les données à ce chemin absolu exact, en lecture seule, sans toucher au moindre XML.

Un docker-compose de validation dédié assemble le tout — data dir migré, rasters montés au bon chemin, sans identifiants admin (le compte d’origine est préservé), HTTPS désactivé :

services:
  geoserver:
    image: allfab/geoserver-ecw:3.0.0
    ports: ["8080:8080"]
    volumes:
      - ./work/config:/app/geoserver/config              # `data dir` migré
      - ./src/data:/opt/data/geoserver/data-src:ro        # rasters au chemin ABSOLU de prod
    environment:
      - HTTPS_ENABLED=false
      # surtout PAS de GEOSERVER_ADMIN_USER / GEOSERVER_ADMIN_PASSWORD

Le verdict, obtenu en interrogeant l’instance (GetCapabilities, puis GetMap sur une couche ECW et une couche JP2ECW) :

Les deux GetMap renvoient de vraies images RGB non vides — l’orthophoto ECW (une dalle de 5,8 Go) comme le plan réglementaire JP2ECW. La preuve que la chaîne ECW → GDAL/Hexagon → GeoServer v3.0.0 fonctionne de bout en bout, sur le runtime Java 21 / Jetty 12.1 final.

Servir la v3.0.0 derrière un reverse-proxy

#

Le rendu fonctionne ; reste à servir GeoServer en production. Et c’est là qu’un dernier piège attendait, révélé dès la première connexion à la console en local :

Content-Security-Policy : Les paramètres de la page ont empêché le chargement
d'une ressource (form-action) à l'adresse https://geo-ressources.example.fr/geoserver/j_spring_security_check
car elle enfreint la directive suivante : « form-action 'self' »

Le formulaire de login est bloqué. La cause : le data dir de production fige un Proxy Base URL sur son domaine public. GeoServer construit toutes ses URL absolues (dont l’action du formulaire) à partir de ce champ ; en accès direct sur localhost, cette URL n’est plus « la même origine », et la CSP form-action 'self' (activée par défaut depuis la v2.27) la rejette.

Ce petit blocage pointe une question d’architecture : où le TLS est-il terminé ?

Deux modèles de terminaison TLS

#

L’image embarque Jetty, capable de terminer le TLS lui-même à partir d’un keystore Java. Mais Let’s Encrypt émet du PEM, pas un keystore : le modèle « Jetty termine le TLS » imposerait une conversion PEM → PKCS12 à chaque renouvellement (tous les 90 jours), remontage et redémarrage. Fastidieux et fragile.

flowchart LR
    subgraph A["Modèle A — Jetty termine le TLS (autonome)"]
        direction LR
        ca["Navigateur"] -- "HTTPS" --> ja["Jetty :8443
+ keystore
(à gérer / renouveler)"]
    end
    subgraph B["Modèle B — terminaison à l'edge (notre cible)"]
        direction LR
        cb["Navigateur"] -- "HTTPS (public)" --> tb["Traefik :443
+ ACME / Let's Encrypt"]
        tb -- "HTTP (interne, clair)" --> jb["Jetty :8080
HTTPS_ENABLED=false"]
    end
    style ja fill:#ffe0b2,stroke:#e65100,stroke-width:2px,color:#000
    style tb fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
    style jb fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000

Dans la future infrastructure de GEO, c’est le modèle B : Traefik termine le TLS et gère les certificats Let’s Encrypt automatiquement (ACME), puis relaie en HTTP clair vers le conteneur sur le réseau interne. Le conteneur GeoServer tourne donc en HTTPS_ENABLED=false — aucun keystore, tout le bloc HTTPS de l’image est court-circuité.

Faire confiance aux en-têtes du proxy

#

En modèle B, GeoServer ne voit qu’une requête HTTP interne. Pour qu’il reconstruise ses URL publiques (et non l’adresse interne), Traefik injecte X-Forwarded-Proto/Host/For, et GeoServer doit les honorer via son global.xml :

<proxyBaseUrl>https://geoserver.example.fr/geoserver</proxyBaseUrl>
<useHeadersProxyURL>true</useHeadersProxyURL>

C’est ce réglage qui, en production, fait pointer l’action du login vers la bonne origine et satisfait la CSP form-action 'self' — le pendant propre du blocage rencontré en local.

Découper la console des services

#

Dernier arbitrage : GeoServer sert deux natures de trafic. La console /web est faite pour des humains ; les services OWS (/wms, /wfs, /ows, /gwc) et l’API REST sont consommés par des machines (QGIS, webmaps, scripts). Placer un SSO interactif (redirection vers une page de login) devant tout le domaine casserait ces clients machine. La route du reverse-proxy est donc scindée :

Conclusion

#

Ce que cette approche apporte :

• Une migration fiable, où chaque version applique ses propres transformations, sans saut hasardeux.
• Un processus reproductible et reprenable : images de palier versionnées, snapshots par marche, reprise à START_STEP.
• Une architecture qui assume les ruptures (deux tiers Java 11/21, trois profils Jetty) au lieu de les subir.
• Un aboutissement concret et validé de bout en bout : le data dir sert ses couches sur le GeoServer v3.0.0 dockerisé de la future infrastructure de GEO, ECW natif par GDAL compris, prêt à passer derrière le reverse-proxy Traefik (TLS Let’s Encrypt).

Image de couverture : Jaume Galofré sur Unsplash.