Déployer l’architecture d’un serveur de tuiles OSM sous Ubuntu 22.04 : prérequis et vérifications

Installer un serveur OSM sous Ubuntu 22.04 consiste à déployer une chaîne de rendu de tuiles : PostgreSQL/PostGIS stocke les données géographiques, osm2pgsql les importe, Mapnik produit l’image, renderd orchestre le rendu et Apache expose les tuiles. Ce n’est pas une simple installation d’OpenStreetMap : vous mettez en place un serveur de tuiles autonome.

Ce guide présente les prérequis, l’architecture et les vérifications à effectuer pour un déploiement de référence avec un extrait régional au format .osm.pbf, pas nécessairement pour la planète entière. Il ne constitue pas une procédure d’installation reproductible de bout en bout tant que le style, la génération du XML Mapnik et la configuration Apache/mod_tile n’ont pas été validés pour les versions réellement installées.

Quel serveur OSM installe-t-on exactement ?

Un serveur OSM peut désigner plusieurs choses : une réplique de données, une API, un géocodeur ou un serveur de tuiles. Ici, il s’agit d’un serveur de rendu cartographique raster : un navigateur, une application web ou un logiciel SIG appelle une URL de tuile, par exemple /osm_tiles/{z}/{x}/{y}.png, et reçoit une image de carte.

La chaîne décrite correspond à l’architecture historique du style cartographique OSM : les données sont chargées dans PostgreSQL/PostGIS, Mapnik interprète le style, renderd lance les rendus demandés et mod_tile fait le lien avec Apache. Le premier affichage d’une zone peut être lent, car les tuiles sont générées à la demande puis mises en cache.

Un serveur de tuiles n’est pas une copie complète du projet OpenStreetMap : c’est une chaîne de stockage, de style, de rendu et de cache à maintenir.

Quels prérequis prévoir avant l’installation ?

La procédure ci-dessous suppose un serveur Ubuntu 22.04 à jour, un accès administrateur via sudo, une connexion réseau et un nom d’hôte ou une adresse IP permettant de tester Apache. Le dimensionnement dépend surtout de l’extrait téléchargé, du nombre de couches activées dans le style et du trafic attendu. Il est donc inutile de promettre une configuration universelle.

Pour un premier déploiement, choisissez une zone réduite ou régionale depuis un fournisseur d’extraits OSM reconnu, tel que Geofabrik. À titre d’exemple, un extrait de pays peut peser quelques dizaines de mégaoctets ou plusieurs gigaoctets : la taille du fichier PBF ne reflète pas directement la taille finale de la base PostGIS ni celle des index.

• Ubuntu Server 22.04 LTS, mis à jour avant l’installation ;
• un compte disposant de sudo ;
• de l’espace disque libre pour le fichier PBF, la base, les index et le cache de tuiles ;
• un extrait OSM au format .osm.pbf ;
• un pare-feu autorisant HTTP ou HTTPS si le service doit être accessible à distance.

Les composants à installer et leur rôle

Avant de lancer des commandes, il faut séparer les responsabilités. Cela évite une erreur fréquente : chercher un problème dans Apache alors que l’import OSM a échoué, ou modifier Mapnik quand renderd pointe simplement vers un mauvais fichier XML.

Composant	Rôle dans le serveur OSM	Point de contrôle
PostgreSQL	Base relationnelle qui héberge les tables importées.	Connexion à la base gis.
PostGIS	Extension géospatiale utilisée pour les objets, géométries et requêtes cartographiques.	Extension activée dans la base.
osm2pgsql	Importe le fichier OSM PBF selon le schéma attendu par le style.	Fin d’import sans erreur SQL.
Mapnik	Transforme données et règles de style en image de carte.	Fichier XML de style accessible.
renderd	Demande, planifie et exécute le rendu des tuiles.	Socket et journal de service.
mod_tile et Apache	Reçoivent les requêtes HTTP et livrent les tuiles en cache ou à rendre.	URI, socket et cache raccordés dans la configuration Apache.

Le dépôt openstreetmap-carto est un exemple de style cartographique à évaluer pour ce type d’architecture. Son dépôt, ses dépendances et ses sources de données externes évoluent : vérifiez toujours le fichier README du commit ou de la version que vous déployez avant de copier une commande d’import.

Comment installer les dépendances sur Ubuntu 22.04 ?

La réponse courte : installez les paquets système, créez un utilisateur de service dédié puis récupérez un style cartographique compatible avec votre version des outils. Ne mélangez pas des instructions prévues pour Ubuntu 12.04, 20.04 ou une ancienne version de PostgreSQL : les chemins, paquets et dépendances ont changé.

Commencez par mettre le système à jour. Cette opération peut nécessiter un redémarrage si le noyau ou des bibliothèques centrales sont remplacés.

sudo apt update
sudo apt upgrade -y
sudo apt install -y \
  apache2 \
  libapache2-mod-tile \
  renderd \
  mapnik-utils \
  python3-mapnik \
  osm2pgsql \
  postgresql \
  postgresql-contrib \
  postgis \
  git \
  curl \
  unzip \
  wget \
  fonts-dejavu-core

Selon les dépôts activés et l’architecture du serveur, certains noms de paquets ou chemins peuvent différer. Vérifiez notamment les versions réellement disponibles avec apt-cache policy renderd osm2pgsql postgresql. Si un paquet n’est pas trouvé, ne forcez pas l’installation depuis un dépôt tiers sans vérifier la compatibilité avec Ubuntu 22.04.

Créez ensuite l’utilisateur système qui possédera le style, les fichiers de rendu et, idéalement, les opérations d’import.

sudo adduser --system --group --home /home/renderer renderer
sudo install -d -o renderer -g renderer /home/renderer/src
sudo install -d -o renderer -g renderer /var/lib/mod_tile

Configurer PostgreSQL et PostGIS pour les données OSM

La base doit être créée avant l’import. Utilisez un rôle PostgreSQL distinct pour le rendu plutôt que le superutilisateur PostgreSQL au quotidien. Le compte renderer n’a pas besoin de droits d’administration généraux pour servir des tuiles après la phase de préparation.

Les commandes suivantes créent un rôle, une base UTF-8 et activent PostGIS. Adaptez les droits et la méthode d’authentification locale si votre politique d’exploitation impose un compte PostgreSQL différent de l’utilisateur système renderer. L’utilisation ultérieure de --username renderer --host localhost dépend notamment de pg_hba.conf et peut demander un mot de passe ou une autre méthode d’authentification.

sudo -u postgres createuser renderer
sudo -u postgres createdb -E UTF8 -O renderer gis
sudo -u postgres psql -d gis -c "CREATE EXTENSION postgis;"
sudo -u postgres psql -d gis -c "CREATE EXTENSION hstore;"

Contrôlez le résultat et l’authentification avant de poursuivre. Une extension absente, une base détenue par le mauvais rôle ou une règle locale incompatible provoquera souvent un échec d’import qui ressemble, à tort, à un problème osm2pgsql.

sudo -u postgres psql -d gis -c "\dx"
sudo -u postgres psql -d gis -c "\du"
sudo -u renderer psql -h localhost -U renderer -d gis -c "SELECT current_user;"

Comment importer les données OpenStreetMap avec osm2pgsql ?

La réponse directe : téléchargez un extrait .osm.pbf, utilisez le mode et le fichier de style exigés par votre projet cartographique, puis lancez osm2pgsql avec les options compatibles avec ce style. Pour certains styles utilisant le schéma classique osm2pgsql, l’option --slim est importante sur les imports significatifs, car elle autorise osm2pgsql à utiliser des tables temporaires sur disque.

Récupérez d’abord le style. Les commandes suivantes installent le dépôt dans le répertoire du compte de service ; elles ne préparent pas à elles seules le style pour le rendu. Consultez la documentation du commit retenu pour installer CartoCSS/carto si nécessaire, télécharger les shapefiles, les données Natural Earth et les polices requises, puis générer le XML Mapnik correspondant.

sudo -u renderer git clone https://github.com/gravitystorm/openstreetmap-carto.git \
  /home/renderer/src/openstreetmap-carto

cd /home/renderer/src/openstreetmap-carto
sudo -u renderer git submodule update --init --recursive

Placez votre extrait dans un dossier lisible par renderer. L’exemple ci-dessous utilise le nom fictif region.osm.pbf : remplacez-le par le chemin réel de votre fichier.

sudo install -d -o renderer -g renderer /home/renderer/data
sudo mv region.osm.pbf /home/renderer/data/
sudo chown renderer:renderer /home/renderer/data/region.osm.pbf

La commande d’import dépend du style réellement choisi, de son schéma d’import et de la version d’osm2pgsql installée. La forme suivante est seulement un exemple pour un style explicitement compatible avec le schéma classique et avec le fichier openstreetmap-carto.style disponible dans le commit retenu ; elle ne permet pas de garantir l’import du dépôt openstreetmap-carto sans validation de sa documentation.

sudo -u renderer osm2pgsql \
  --create \
  --slim \
  --database gis \
  --username renderer \
  --host localhost \
  --style /home/renderer/src/openstreetmap-carto/openstreetmap-carto.style \
  /home/renderer/data/region.osm.pbf

Ne lancez pas l’import en arrière-plan sans journal exploitable. Redirigez au besoin la sortie vers un fichier et surveillez l’espace disponible avec df -h. La durée dépend du fichier, des index, du stockage et des ressources disponibles ; elle doit être mesurée sur votre machine, pas déduite d’un exemple trouvé ailleurs.

Le bon premier objectif n’est pas d’importer la planète entière : c’est d’obtenir une base cohérente, un style préparé et une configuration validée sur une zone limitée.

Configurer Mapnik, renderd et Apache

Le point de jonction est le fichier renderd.conf. Il indique à renderd où trouver le socket, le répertoire de cache, les bibliothèques Mapnik et le fichier XML décrivant le style. Apache, via mod_tile, doit être configuré pour raccorder l’URI de tuiles, le socket renderd et le répertoire de cache correspondant.

Le dépôt openstreetmap-carto contient généralement des fichiers de projet à convertir ou à préparer selon la version employée. Si le projet requiert l’outil CartoCSS carto, installez-le uniquement selon les instructions du dépôt, récupérez toutes les données externes et les polices indiquées, puis générez le XML Mapnik pour le commit choisi : un fichier XML généré pour un autre commit du style peut fonctionner partiellement ou échouer sur des couches manquantes.

Les commandes ci-dessous décrivent une structure de configuration ; elles ne constituent pas une procédure complète tant que le style n’a pas été préparé et que la configuration Apache/mod_tile n’a pas été validée sur l’installation cible.

Inspectez le chemin des plugins Mapnik présent sur votre serveur :

mapnik-config --input-plugins
mapnik-config --fonts

Éditez ensuite /etc/renderd.conf. Les valeurs suivantes illustrent la structure attendue ; les chemins plugins_dir et XML doivent correspondre à votre installation réelle, et le fichier mapnik.xml doit avoir été généré par la procédure documentée du style retenu.

[renderd]
socketname=/run/renderd/renderd.sock
num_threads=2
tile_dir=/var/lib/mod_tile

[mapnik]
plugins_dir=/usr/lib/mapnik/3.0/input
font_dir=/usr/share/fonts
font_dir_recurse=true

[default]
URI=/osm_tiles/
XML=/home/renderer/src/openstreetmap-carto/mapnik.xml
HOST=localhost
TILESIZE=256
MAXZOOM=20

Le nombre de threads est un arbitrage : davantage de rendus parallèles peut réduire la file d’attente, mais augmente la charge CPU, la consommation mémoire et la pression sur PostgreSQL. Commencez avec une valeur prudente, observez les journaux et ajustez seulement après avoir validé le service.

Avant d’activer les services, vérifiez le fichier de configuration réellement utilisé par l’unité renderd, l’utilisateur sous lequel elle démarre et les permissions du répertoire /run/renderd. Le socket /run/renderd/renderd.sock doit être créé par renderd avec des droits permettant à Apache/mod_tile d’y accéder ; cela dépend de l’unité systemd et de la configuration des paquets installés.

L’activation du module Apache et le redémarrage des services ne suffisent pas à exposer automatiquement /osm_tiles/. Validez dans la configuration fournie par votre paquet ou dans votre virtual host les directives mod_tile qui relient explicitement l’URI, le socket renderd et le cache utilisés. Ne redémarrez Apache qu’après cette vérification.

sudo a2enmod tile
sudo systemctl enable --now postgresql
sudo systemctl enable --now renderd
sudo systemctl restart apache2

sudo systemctl status renderd --no-pager
sudo systemctl status apache2 --no-pager
sudo ls -l /run/renderd/renderd.sock
sudo ls -ld /var/lib/mod_tile

• Vérifiez que renderd lit bien le fichier de configuration attendu et démarre avec l’utilisateur prévu ;
• contrôlez les droits sur /var/lib/mod_tile, sur /run/renderd et sur le socket ;
• assurez-vous que l’URI configurée dans renderd correspond à celle explicitement exposée par mod_tile dans Apache ;
• vérifiez que la configuration Apache pointe vers le même socket et le même répertoire de cache que renderd ;
• n’ouvrez le port 80 ou 443 qu’après un test local réussi.

Tester le rendu des tuiles et diagnostiquer les erreurs

Le premier test doit être local, après validation du style, du XML Mapnik, du socket et de la configuration Apache/mod_tile. Demandez une tuile très générale à Apache avec l’URI définie dans renderd.conf. Le critère de réussite est une réponse HTTP 200, un fichier non vide et un type détecté comme image PNG ; ces contrôles confirment alors que la chaîne Apache → mod_tile → renderd → Mapnik → PostGIS répond correctement.

Avec l’exemple de configuration précédent, lancez :

curl -I http://127.0.0.1/osm_tiles/0/0/0.png
curl -f -o tuile-test.png http://127.0.0.1/osm_tiles/0/0/0.png
test -s tuile-test.png
file tuile-test.png

Le résultat de file tuile-test.png doit indiquer une image PNG et test -s ne doit produire aucune erreur. Une erreur 404 indique souvent une URI mod_tile ou Apache mal déclarée. Une réponse 500, un délai excessif ou un fichier vide renvoient plus fréquemment à renderd, au style ou à la base. Ne modifiez pas plusieurs couches à la fois : consultez les journaux, identifiez le premier message d’erreur utile, puis corrigez une seule cause.

Symptôme	Cause probable	Vérification utile
Erreur 404 sur l’URL de tuile	URI Apache différente de celle de renderd.	Comparer la directive mod_tile et URI=.
Erreur 500 ou rendu impossible	Chemin XML, police, plugin Mapnik ou couche absente.	Lire les logs renderd et vérifier le XML.
Erreur de connexion PostgreSQL	Rôle, droits ou authentification locale incorrects.	Tester psql -h localhost -U renderer -d gis avec le rôle concerné.
Rendu très lent	Tuile non présente dans le cache ou requête coûteuse.	Observer CPU, mémoire, disque et logs PostgreSQL.
Carte incomplète	Données externes ou import non conformes au style.	Lire le README du style et les erreurs de couches.

Les commandes suivantes affichent les journaux les plus utiles pendant un test. Elles doivent être exécutées dans un second terminal pendant que vous demandez une tuile.

sudo journalctl -u renderd -f
sudo journalctl -u apache2 -f
sudo tail -f /var/log/apache2/error.log
sudo -u postgres psql -d gis -c "SELECT PostGIS_Version();"

Sécuriser et maintenir le serveur de tuiles

Une installation qui affiche une première tuile n’est pas encore un service exploitable durablement. Protégez l’accès d’administration, appliquez les mises à jour de sécurité Ubuntu, limitez l’exposition réseau et surveillez la croissance de la base et du cache. Si le serveur devient public, ajoutez HTTPS et des limites de requêtes adaptées à votre frontal web.

La mise à jour des données est un sujet distinct du premier import. Les mécanismes d’actualisation par diffs existent, mais demandent une stratégie cohérente autour du style, de la réplication et de l’invalidation de cache. Pour un premier serveur OSM sous Ubuntu 22.04, un réimport planifié d’un extrait peut être plus simple à opérer qu’une réplication continue mal maîtrisée.

Sources utiles à consulter

• Switch2OSM : procédure de référence dédiée à Ubuntu 22.04 à recouper avec les versions de paquets réellement installées et la configuration Apache/mod_tile cible.
• Documentation osm2pgsql : options d’import, modes de traitement et compatibilité avec les styles.
• Documentation PostGIS : installation, extensions et contrôles de version de la base géospatiale.
• Dépôt openstreetmap-carto : dépendances, préparation du style, données externes et génération des fichiers nécessaires au rendu.
• Wiki OpenStreetMap sur les serveurs de tuiles : architecture, bonnes pratiques et limites d’usage.

Questions fréquentes sur un serveur OSM sous Ubuntu

Peut-on installer un serveur OSM sans importer la planète entière ?

Oui. Un extrait régional ou national au format PBF suffit pour valider l’architecture et fournir une carte locale. C’est généralement le meilleur point de départ, car la taille de la base, le temps d’import et la charge de rendu restent plus faciles à observer.

Pourquoi Apache répond-il mais n’affiche aucune tuile ?

Apache peut fonctionner alors que renderd, Mapnik ou PostgreSQL échoue en arrière-plan. Vérifiez d’abord le statut de renderd, puis les journaux système, le chemin du fichier XML déclaré dans renderd.conf, les droits du socket et les directives Apache/mod_tile. Contrôlez aussi que l’URI demandée correspond bien à celle configurée.

Faut-il utiliser un compte PostgreSQL superutilisateur pour osm2pgsql ?

Non, ce n’est pas souhaitable pour l’exploitation courante. Créez la base et ses extensions avec un compte d’administration, puis donnez au rôle d’import les droits nécessaires sur cette base. Vérifiez également que l’authentification définie dans pg_hba.conf permet la connexion réellement utilisée par osm2pgsql.

Comment mettre à jour les données OSM après le premier import ?

Vous pouvez soit réimporter périodiquement un nouvel extrait, soit mettre en place une réplication par diffs. La seconde méthode est plus exigeante : elle nécessite de gérer la cohérence des données, du style et du cache. Pour un usage local ou peu fréquent, un réimport planifié est souvent plus simple à contrôler.