Développement

Héberger ses propres cartes Protomaps (PMTiles) sur un VPS

Votre client veut une carte sur sa page contact, et vous la branchez sur une API commerciale. Quelques mois plus tard, la facture suit la fréquentation du site, et la clé, visible dans le code de la page, peut être copiée par n'importe qui. Il existe une voie plus sobre : une archive PMTiles posée sur un VPS, servie par nginx en requêtes par plage d'octets, affichée par MapLibre GL JS. Aucun serveur de cartes à administrer. Ce guide donne les commandes, la taille réelle des fichiers, les erreurs rencontrées et leurs messages exacts.

11 min de lecture7 étapes

Orbi agent IALe sommaire suit l’article ; les articles liés vous attendent en bas de page.

Sommaire· Pourquoi servir ses propres cartes plutôt que louer des tuiles1/12
  1. 01Pourquoi servir ses propres cartes plutôt que louer des tuiles
  2. 02Ce que change un fichier PMTiles
  3. 03Combien ça pèse vraiment : planète, région, satellite
  4. 04Choisir entre API à clé, OpenFreeMap et PMTiles sur votre VPS
  5. 05Prérequis à réunir avant de commencer
  6. 06Mise en place en sept étapes
  7. 07Lire le bloc nginx ligne par ligne
  8. 08Derrière Cloudflare : ce que la documentation permet d'affirmer
  9. 09Dépannage : les erreurs réellement rencontrées
  10. 10Attribution OpenStreetMap : l'obligation de licence
  11. 11Durcir et entretenir le serveur de tuiles
  12. 12Brancher ce serveur de cartes sur votre parc de sites

Pourquoi servir ses propres cartes plutôt que louer des tuiles

Une page contact avec un plan, un localisateur de magasins, une carte de livraison : presque tous les sites clients en portent une. Le réflexe est d'intégrer une API de cartes commerciale, avec une clé. Deux problèmes apparaissent avec le temps. D'abord la facture : elle suit le nombre de chargements de carte, donc la fréquentation du site, que l'agence ne maîtrise pas. Ensuite la clé : placée dans le code de la page, elle est lisible par n'importe quel visiteur. La restreindre aux domaines autorisés limite l'abus sans le supprimer, car l'en-tête qui identifie le site d'origine se falsifie depuis un simple script. La parade est de ne plus dépendre d'une clé : vous hébergez vous-même les tuiles, dans un seul fichier, sur le serveur qui héberge déjà le site.

Ce que change un fichier PMTiles

  • Une seule archive — toutes les tuiles vectorielles d'une zone tiennent dans un fichier unique, sans dossier de millions de petites images à synchroniser.
  • Aucun serveur de cartes — le navigateur lit le fichier par requêtes HTTP Range, c'est-à-dire par morceaux d'octets. Un serveur web ordinaire suffit.
  • Pas de clé dans la page — il n'y a plus de secret à voler ni de quota à épuiser : la carte est une ressource statique de votre propre domaine.
  • Une facture qui ne suit plus les visites — le coût devient celui du VPS et de sa bande passante, deux postes que vous connaissez.
  • Un fichier par zone, partagé entre clients — une extraction régionale peut servir tous les sites de vos clients situés dans cette zone.
  • Un style libre — MapLibre GL JS est open source, et les couleurs, les libellés et les couches se règlent côté client.

Combien ça pèse vraiment : planète, région, satellite

L'objection habituelle tient en un mot, le poids. Le fond de carte planétaire complet fait de l'ordre de 120 Go selon la documentation de Protomaps, et la build que nous avons interrogée annonçait environ 140 Go. Ce n'est pas ce que l'on pose sur le site d'un client, et ce n'est pas nécessaire. L'outil pmtiles extract découpe une zone dans l'archive distante sans la télécharger en entier. Sur un cadre d'environ 22 km sur 17 km autour de Paris, tous niveaux de zoom compris, le fichier obtenu pèse 49 Mo, et l'extraction a pris une quinzaine de secondes. Chaque niveau de zoom supplémentaire double à peu près la taille : l'option --maxzoom est le levier si un plan de magasin n'a pas besoin du détail maximal.

Une limite à dire franchement. Ce fichier est un fond vectoriel : il dessine la carte, il ne géocode pas et ne calcule pas d'itinéraire. Quant à l'imagerie satellite haute résolution, elle reste très coûteuse en stockage et sort du périmètre de ce guide.

Choisir entre API à clé, OpenFreeMap et PMTiles sur votre VPS

Faites défiler le tableau

CritèreAPI commerciale à cléOpenFreeMap (instance publique)PMTiles sur votre VPS
CoûtÀ l'usage, il suit les chargements de carteAucun frais ni clé ; le projet couvre ses coûts par des donsCelui de votre VPS et de sa bande passante
Clé dans la pageOui, lisible par tout visiteurAucune clé, aucun compteAucune clé
DépendanceUn fournisseur et ses conditionsUn service public tenu par un projet tiersVotre serveur, vos règles
Mise en placeUne clé et quelques lignesUne URL de styleUne extraction, un bloc nginx, une page
Imagerie satelliteSelon le fournisseurNon : fond vectoriel OpenStreetMapNon : stockage très lourd à votre charge
À choisir quandVous avez besoin d'imagerie, de géocodage ou d'itinérairesUn prototype ou un site à faible enjeu, sans infrastructure à tenirUn parc de sites clients dont vous voulez maîtriser facture et disponibilité

Prérequis à réunir avant de commencer

Un VPS dont le disque est dimensionné sur la taille de vos archives, plus une marge pour remplacer un fichier sans interruption : comptez deux fois la plus grosse archive. Un nginx à jour, ou un Caddy si vous préférez qu'il gère seul le HTTPS ; la comparaison est dans l'article Caddy ou Nginx sur un VPS. Un sous-domaine dédié aux tuiles, avec un certificat TLS : une page en HTTPS qui chargerait des tuiles en HTTP serait bloquée comme contenu mixte. Enfin un poste avec accès SSH pour lancer la ligne de commande pmtiles. Le service d'un fichier statique par plages d'octets est peu gourmand en processeur : ce sont le disque et la bande passante qui dimensionnent la machine.

Mise en place en sept étapes

  1. Installer la ligne de commande pmtiles

    C'est un binaire unique, sans dépendance, publié sur la page des versions du dépôt protomaps/go-pmtiles sur GitHub. Sous Linux :

    tar -xzf go-pmtiles_*_Linux_x86_64.tar.gz
    sudo mv pmtiles /usr/local/bin/

  2. Extraire votre région

    Choisissez une build listée sur maps.protomaps.com/builds et indiquez le cadre au format MIN_LON,MIN_LAT,MAX_LON,MAX_LAT, longitude avant latitude :

    pmtiles extract https://build.protomaps.com/AAAAMMJJ.pmtiles paris.pmtiles --bbox=2.2,48.8,2.5,48.95

    Protomaps déconseille de pointer le site directement vers ses téléchargements : l'extrait, lui, vous appartient. L'archive source doit être « clustered », ce que sont les builds officielles.

  3. Contrôler l'archive obtenue

    pmtiles show paris.pmtiles affiche les bornes, les niveaux de zoom et la compression interne ; pmtiles verify paris.pmtiles vérifie l'ordre et l'en-tête. Notez la compression interne gzip : c'est la raison du gzip off plus bas.

  4. Copier le fichier sur le VPS

    rsync -avP paris.pmtiles deploy@votre-vps:/var/www/tuiles/

    Pour une mise à jour ultérieure, envoyez le nouveau fichier sous un autre nom dans le même dossier, puis renommez-le avec mv.

  5. Déclarer le serveur nginx

    Ajoutez ce bloc pour le sous-domaine, avec vos lignes ssl_certificate habituelles :

    server {
    listen 443 ssl;
    server_name tuiles.votre-domaine.com;
    root /var/www/tuiles;
    default_type application/octet-stream;
    location / {
    gzip off;
    add_header Access-Control-Allow-Origin "https://votre-domaine.com" always;
    add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Range, If-Match" always;
    add_header Access-Control-Expose-Headers "ETag" always;
    add_header Cache-Control "public, max-age=86400" always;
    if ($request_method = OPTIONS) {
    add_header Access-Control-Allow-Origin "https://votre-domaine.com" always;
    add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Range, If-Match" always;
    add_header Access-Control-Max-Age 3600 always;
    return 204;
    }
    }
    }

  6. Recharger nginx et vérifier le 206

    sudo nginx -t && sudo systemctl reload nginx

    Demandez ensuite les 16 384 premiers octets, ceux que lit le client avant toute tuile :

    curl -s -o /dev/null -D - -H "Origin: https://votre-domaine.com" -r 0-16383 https://tuiles.votre-domaine.com/paris.pmtiles

    On attend HTTP/2 206, content-range: bytes 0-16383/ suivi de la taille totale du fichier, content-length: 16384, accept-ranges: bytes et l'en-tête access-control-allow-origin. Un 200 signifie que la plage a été ignorée : passez au dépannage plus bas.

  7. Afficher la carte avec MapLibre GL JS

    npm install maplibre-gl pmtiles @protomaps/basemaps

    Puis, dans le script de la page, avec un élément <div id="map"> :

    import maplibregl from 'maplibre-gl';
    import 'maplibre-gl/dist/maplibre-gl.css';
    import { Protocol } from 'pmtiles';
    import { layers, namedFlavor } from '@protomaps/basemaps';
    const protocol = new Protocol();
    maplibregl.addProtocol('pmtiles', protocol.tile);
    const map = new maplibregl.Map({
    container: 'map',
    center: [2.35, 48.86],
    zoom: 11,
    style: {
    version: 8,
    glyphs: 'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf',
    sprite: 'https://protomaps.github.io/basemaps-assets/sprites/v4/light',
    sources: {
    protomaps: {
    type: 'vector',
    url: 'pmtiles://https://tuiles.votre-domaine.com/paris.pmtiles',
    attribution: '<a href="https://protomaps.com">Protomaps</a> © <a href="https://openstreetmap.org">OpenStreetMap</a>'
    }
    },
    layers: layers('protomaps', namedFlavor('light'), { lang: 'en' })
    }
    });

    Le préfixe pmtiles:// se place devant l'URL HTTPS complète du fichier. Les polices et les pictogrammes pointent ici vers les ressources publiées par Protomaps ; pour ne dépendre de personne, copiez le dépôt protomaps/basemaps-assets sur votre serveur et changez les deux URL.

Lire le bloc nginx ligne par ligne

Il n'existe pas de directive pour activer les plages d'octets : nginx les gère de lui-même sur un fichier statique, et la documentation ne mentionne que max_ranges, dont la valeur 0 les désactive. Le gzip off protège ces plages : les octets demandés sont ceux du fichier tel qu'il est stocké, et une réponse recompressée en route les fausse ; la compression est déjà dans l'archive. L'en-tête Access-Control-Allow-Headers contient Range parce que le navigateur envoie d'abord une requête de préflight OPTIONS avant une lecture partielle, d'où le bloc if qui répond 204. Access-Control-Expose-Headers: ETag laisse la bibliothèque détecter qu'un fichier a été remplacé. Enfin, nginx n'hérite des add_header d'un niveau supérieur que si le niveau courant n'en définit aucun : le bloc if répète donc les siens, et always les envoie aussi sur les réponses d'erreur.

Derrière Cloudflare : ce que la documentation permet d'affirmer

Un fichier de cartes derrière un proxy se comporte mal si l'on ignore trois règles, toutes tirées de la documentation de Cloudflare. L'extension .pmtiles ne figure pas dans la liste des extensions mises en cache par défaut : sans règle de cache, le fichier est relu à chaque fois sur votre origine. La taille maximale d'un fichier en cache est de 512 Mo sur les offres Free, Pro et Business : un extrait régional passe, une archive planétaire non. Et une réponse 206 n'est mise en cache que si elle n'est pas encodée, avec un Content-Range cohérent. Vérifiez le résultat avec l'en-tête cf-cache-status. Les réglages de zone de ce type sont détaillés dans Cloudflare pour un site client. Un sous-domaine en DNS seul évite la question, au prix d'une IP d'origine exposée : à arbitrer avec le reste du parc.

Dépannage : les erreurs réellement rencontrées

  • has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource — l'en-tête manque ou l'origine ne correspond pas exactement : http au lieu de https, ou www en trop. Corrigez la valeur de Access-Control-Allow-Origin, sans oublier always.
  • Request header field range is not allowed by Access-Control-Allow-Headers in preflight response — le préflight ne cite pas Range. Ajoutez-le à Access-Control-Allow-Headers et répondez 204 aux requêtes OPTIONS.
  • Server returned no content-length header or content-length exceeding request. Check that your storage backend supports HTTP Byte Serving. — le serveur a renvoyé le fichier entier avec un 200 au lieu d'un 206. Rejouez le curl : un proxy, un max_ranges 0 ou une compression en route en sont les causes.
  • Wrong magic number for PMTiles archive — ce que reçoit le client n'est pas une archive PMTiles : page d'erreur HTML, mauvais chemin, ou fichier tronqué par un envoi interrompu. Comparez la taille sur le serveur et sur votre poste.
  • Server returned non-matching ETag … after one retry — le fichier a changé pendant la lecture, ou deux versions se mélangent dans un cache. Remplacez le fichier par un mv, jamais par une copie en place.
  • Carte blanche, fond sans libellé ni routes — les polices ou les pictogrammes ne se chargent pas : ouvrez l'onglet réseau et cherchez les 404 sur glyphs et sprite.
  • Aucune mention OpenStreetMap à l'écran — la carte s'affiche, mais la licence n'est pas respectée. Voir la section suivante.

Attribution OpenStreetMap : l'obligation de licence

Les données viennent d'OpenStreetMap, publiées sous la licence ODbL. Le fond de Protomaps est distribué comme une œuvre produite sous cette licence, avec attribution à OpenStreetMap exigée. OpenStreetMap demande de créditer le projet et de préciser que les données sont sous licence ODbL, par exemple avec un lien vers openstreetmap.org/copyright. Dans MapLibre, le champ attribution de la source s'affiche dans le coin de la carte : gardez-le visible, et ne masquez pas ce contrôle dans la feuille de style d'un client. Aucune erreur ne signale l'oubli, ce qui le rend facile à livrer sans s'en apercevoir.

Durcir et entretenir le serveur de tuiles

Autorisez une origine exacte, jamais * : Protomaps recommande d'indiquer votre propre domaine. Pour plusieurs sites clients, remplacez la valeur fixe par un map $http_origin qui ne renvoie que les domaines d'une liste. Surveillez la bande passante du sous-domaine dans vos journaux nginx : c'est désormais votre poste de coût. Replanifiez l'extraction à intervalle régulier, vers un fichier temporaire, puis mv.

Brancher ce serveur de cartes sur votre parc de sites

Comme l'archive est un fichier statique, un seul sous-domaine de tuiles peut servir les cartes de tous les sites clients d'une même zone : un fichier, un certificat, une sauvegarde. Il vit naturellement sur le VPS qui héberge déjà vos sites, ce qui évite un fournisseur de plus à suivre ; le choix entre VPS et mutualisé est traité dans Hébergement mutualisé ou VPS pour un site client. Si un client réclame de l'imagerie satellite ou des itinéraires, gardez une API commerciale pour ce site seul, et laissez les autres sur votre archive.

Partager cet articleservorbit.com/ma-fr/blog/heberger-cartes-protomaps-pmtiles-vps

Un parc de sites clients, un seul endroit

Prix HT affichés avec leur renouvellement.