Desarrollo

Aloja tus propios mapas Protomaps (PMTiles) en un VPS

Tu cliente quiere un mapa en su página de contacto y lo conectas a una API comercial. Unos meses después, la factura sigue el tráfico del sitio, y la clave, visible en el código de la página, la puede copiar cualquiera. Hay una vía más sobria: un archivo PMTiles en un VPS, servido por nginx con peticiones por rango de bytes y mostrado con MapLibre GL JS. Sin servidor de mapas que administrar. Esta guía da los comandos, el tamaño real de los archivos, los errores que aparecen y sus mensajes exactos.

11 min de lectura7 pasos

Orbi agente IAEl índice sigue al artículo; los artículos relacionados le esperan al final.

Contenido· Por qué servir tus propios mapas en lugar de alquilar teselas1/12
  1. 01Por qué servir tus propios mapas en lugar de alquilar teselas
  2. 02Lo que cambia un archivo PMTiles
  3. 03Cuánto pesa de verdad: planeta, región, satélite
  4. 04Elegir entre una API con clave, OpenFreeMap y PMTiles en tu VPS
  5. 05Requisitos que reunir antes de empezar
  6. 06Puesta en marcha en siete pasos
  7. 07Leer el bloque nginx línea por línea
  8. 08Detrás de Cloudflare: lo que la documentación permite afirmar
  9. 09Solución de errores: los que realmente aparecen
  10. 10Atribución a OpenStreetMap: la obligación de la licencia
  11. 11Reforzar y mantener el servidor de teselas
  12. 12Conectar este servidor de mapas a tu cartera de sitios

Por qué servir tus propios mapas en lugar de alquilar teselas

Una página de contacto con un plano, un localizador de tiendas, un mapa de entregas: casi todos los sitios de clientes llevan uno. El reflejo habitual es integrar una API de mapas comercial, con una clave. Con el tiempo aparecen dos problemas. Primero la factura: sigue el número de cargas de mapa, es decir, el tráfico del sitio, que la agencia no controla. Después la clave: colocada en el código de la página, la lee cualquier visitante. Restringirla a los dominios autorizados limita el abuso sin eliminarlo, porque la cabecera que identifica el sitio de origen se falsifica desde un simple script. La salida es dejar de depender de una clave: alojas tú mismo las teselas, en un único archivo, en el servidor que ya aloja el sitio.

Lo que cambia un archivo PMTiles

  • Un único archivo — todas las teselas vectoriales de una zona caben en un solo fichero, sin una carpeta con millones de imágenes pequeñas que sincronizar.
  • Ningún servidor de mapas — el navegador lee el archivo con peticiones HTTP Range, es decir, por trozos de bytes. Un servidor web corriente basta.
  • Sin clave en la página — no hay secreto que robar ni cuota que agotar: el mapa es un recurso estático de tu propio dominio.
  • Una factura que ya no sigue las visitas — el coste pasa a ser el del VPS y su ancho de banda, dos partidas que ya conoces.
  • Un archivo por zona, compartido entre clientes — una extracción regional puede servir a todos los sitios de tus clientes situados en esa zona.
  • Un estilo libre — MapLibre GL JS es de código abierto, y los colores, las etiquetas y las capas se ajustan en el cliente.

Cuánto pesa de verdad: planeta, región, satélite

La objeción habitual cabe en una palabra: el peso. El mapa base completo del planeta ronda los 120 GB según la documentación de Protomaps, y la build que consultamos anunciaba unos 140 GB. No es lo que se pone en el sitio de un cliente, y no hace falta. La herramienta pmtiles extract recorta una zona del archivo remoto sin descargarlo entero. Sobre un encuadre de unos 22 km por 17 km alrededor de París, con todos los niveles de zoom, el archivo resultante pesa 49 MB, y la extracción tardó unos quince segundos. Cada nivel de zoom adicional duplica aproximadamente el tamaño: la opción --maxzoom es la palanca si el plano de una tienda no necesita el detalle máximo.

Un límite que hay que decir con franqueza. Este archivo es un mapa base vectorial: dibuja el mapa, no geocodifica ni calcula rutas. En cuanto a las imágenes de satélite de alta resolución, siguen siendo muy costosas en almacenamiento y quedan fuera de esta guía.

Elegir entre una API con clave, OpenFreeMap y PMTiles en tu VPS

Desplace la tabla

CriterioAPI comercial con claveOpenFreeMap (instancia pública)PMTiles en tu VPS
CostePor uso, sigue las cargas de mapaSin tarifa ni clave; el proyecto cubre sus costes con donacionesEl de tu VPS y su ancho de banda
Clave en la páginaSí, legible por cualquier visitanteSin clave ni cuentaSin clave
DependenciaUn proveedor y sus condicionesUn servicio público mantenido por un proyecto externoTu servidor, tus reglas
Puesta en marchaUna clave y unas líneasUna URL de estiloUna extracción, un bloque nginx, una página
Imágenes de satéliteSegún el proveedorNo: mapa base vectorial de OpenStreetMapNo: almacenamiento muy pesado a tu cargo
Elígelo cuandoNecesitas imágenes, geocodificación o rutasUn prototipo o un sitio de poca importancia, sin infraestructura que mantenerUna cartera de sitios de clientes cuya factura y disponibilidad quieres controlar

Requisitos que reunir antes de empezar

Un VPS con un disco dimensionado según tus archivos, más un margen para reemplazar un fichero sin interrupción: cuenta el doble del archivo más grande. Un nginx actualizado, o Caddy si prefieres que gestione solo el HTTPS; la comparación está en el artículo Caddy o Nginx en un VPS. Un subdominio dedicado a las teselas, con certificado TLS: una página HTTPS que cargara teselas por HTTP quedaría bloqueada como contenido mixto. Por último, un equipo con acceso SSH para lanzar la línea de comandos pmtiles. Servir un archivo estático por rangos de bytes consume poco procesador: el disco y el ancho de banda dimensionan la máquina.

Puesta en marcha en siete pasos

  1. Instalar la línea de comandos pmtiles

    Es un binario único, sin dependencias, publicado en la página de versiones del repositorio protomaps/go-pmtiles en GitHub. En Linux:

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

  2. Extraer tu región

    Elige una build listada en maps.protomaps.com/builds e indica el encuadre con el formato MIN_LON,MIN_LAT,MAX_LON,MAX_LAT, longitud antes que latitud:

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

    Protomaps desaconseja apuntar tu sitio directamente a sus descargas: el extracto, en cambio, es tuyo. El archivo de origen debe estar «clustered», como lo están las builds oficiales.

  3. Comprobar el archivo obtenido

    pmtiles show paris.pmtiles muestra los límites, los niveles de zoom y la compresión interna; pmtiles verify paris.pmtiles comprueba el orden y la cabecera. Fíjate en la compresión interna gzip: es la razón del gzip off más abajo.

  4. Copiar el archivo al VPS

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

    Para una actualización posterior, envía el nuevo archivo con otro nombre a la misma carpeta y renómbralo después con mv.

  5. Declarar el servidor nginx

    Añade este bloque para el subdominio, con tus líneas ssl_certificate habituales:

    server {
    listen 443 ssl;
    server_name tiles.your-domain.com;
    root /var/www/tuiles;
    default_type application/octet-stream;
    location / {
    gzip off;
    add_header Access-Control-Allow-Origin "https://your-domain.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://your-domain.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. Recargar nginx y comprobar el 206

    sudo nginx -t && sudo systemctl reload nginx

    Pide después los primeros 16 384 bytes, los que lee el cliente antes de cualquier tesela:

    curl -s -o /dev/null -D - -H "Origin: https://your-domain.com" -r 0-16383 https://tiles.your-domain.com/paris.pmtiles

    Se espera HTTP/2 206, content-range: bytes 0-16383/ seguido del tamaño total del archivo, content-length: 16384, accept-ranges: bytes y la cabecera access-control-allow-origin. Un 200 indica que se ignoró el rango: pasa a la lista de solución de errores más abajo.

  7. Mostrar el mapa con MapLibre GL JS

    npm install maplibre-gl pmtiles @protomaps/basemaps

    Después, en el script de la página, con un elemento <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://tiles.your-domain.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' })
    }
    });

    El prefijo pmtiles:// va delante de la URL HTTPS completa del archivo. Las fuentes y los iconos apuntan aquí a los recursos publicados por Protomaps; para no depender de nadie, copia el repositorio protomaps/basemaps-assets a tu servidor y cambia las dos URL.

Leer el bloque nginx línea por línea

No existe una directiva para activar los rangos de bytes: nginx los gestiona por sí mismo en un archivo estático, y la documentación solo menciona max_ranges, cuyo valor 0 los desactiva. El gzip off protege esos rangos: los bytes pedidos son los del archivo tal como está almacenado, y una respuesta recomprimida por el camino los falsearía; la compresión ya está dentro del archivo. La cabecera Access-Control-Allow-Headers contiene Range porque el navegador envía primero una petición de preflight OPTIONS antes de una lectura parcial, de ahí el bloque if que responde 204. Access-Control-Expose-Headers: ETag permite a la biblioteca detectar que un archivo fue reemplazado. Por último, nginx solo hereda los add_header de un nivel superior si el nivel actual no define ninguno: el bloque if repite por eso los suyos, y always los envía también en las respuestas de error.

Detrás de Cloudflare: lo que la documentación permite afirmar

Un archivo de mapas detrás de un proxy se comporta mal si se ignoran tres reglas, todas sacadas de la documentación de Cloudflare. La extensión .pmtiles no figura en la lista de extensiones que se guardan en caché por defecto: sin una regla de caché, el archivo se lee cada vez desde tu origen. El tamaño máximo de un archivo en caché es de 512 MB en los planes Free, Pro y Business: un extracto regional cabe, un archivo del planeta no. Y una respuesta 206 solo se guarda en caché si no está codificada, con un Content-Range coherente. Comprueba el resultado con la cabecera cf-cache-status. Los ajustes de zona de este tipo se detallan en Cloudflare para el sitio de un cliente. Un subdominio solo con DNS evita la cuestión, al precio de una IP de origen expuesta: decídelo con el resto de tu cartera.

Solución de errores: los que realmente aparecen

  • has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource — falta la cabecera o el origen no coincide exactamente: http en lugar de https, o un www de más. Corrige el valor de Access-Control-Allow-Origin, sin olvidar always.
  • Request header field range is not allowed by Access-Control-Allow-Headers in preflight response — el preflight no cita Range. Añádelo a Access-Control-Allow-Headers y responde 204 a las peticiones OPTIONS.
  • Server returned no content-length header or content-length exceeding request. Check that your storage backend supports HTTP Byte Serving. — el servidor devolvió el archivo entero con un 200 en lugar de un 206. Repite el curl: un proxy, un max_ranges 0 o una compresión por el camino son las causas.
  • Wrong magic number for PMTiles archive — lo que recibe el cliente no es un archivo PMTiles: una página de error HTML, una ruta equivocada o un archivo truncado por una subida interrumpida. Compara el tamaño en el servidor y en tu equipo.
  • Server returned non-matching ETag … after one retry — el archivo cambió durante la lectura, o dos versiones se mezclan en una caché. Reemplaza el archivo con mv, nunca con una copia en el mismo sitio.
  • Mapa en blanco, fondo sin etiquetas ni carreteras — las fuentes o los iconos no se cargan: abre la pestaña de red y busca respuestas 404 en glyphs y sprite.
  • Ninguna mención de OpenStreetMap en pantalla — el mapa se muestra, pero no se respeta la licencia. Mira la sección siguiente.

Atribución a OpenStreetMap: la obligación de la licencia

Los datos proceden de OpenStreetMap, publicados bajo la licencia ODbL. El mapa base de Protomaps se distribuye como obra producida bajo esa licencia, con atribución a OpenStreetMap obligatoria. OpenStreetMap pide acreditar el proyecto e indicar que los datos están bajo la ODbL, por ejemplo con un enlace a openstreetmap.org/copyright. En MapLibre, el campo attribution de la fuente aparece en la esquina del mapa: mantenlo visible, y no ocultes este control en la hoja de estilos de un cliente. Ningún error señala el olvido, lo que facilita entregarlo sin darse cuenta.

Reforzar y mantener el servidor de teselas

Autoriza un origen exacto, nunca *: Protomaps recomienda indicar tu propio dominio. Para varios sitios de clientes, sustituye el valor fijo por un map $http_origin que solo devuelva los dominios de una lista. Vigila el ancho de banda del subdominio en tus registros de nginx: ahora es tu partida de coste. Programa la extracción a intervalos regulares, hacia un archivo temporal, y después mv.

Conectar este servidor de mapas a tu cartera de sitios

Como el archivo es estático, un único subdominio de teselas puede servir los mapas de todos los sitios de clientes de una misma zona: un archivo, un certificado, una copia de seguridad. Vive de forma natural en el VPS que ya aloja tus sitios, lo que evita un proveedor más que seguir; la elección entre VPS y hosting compartido se trata en Hosting compartido o VPS para el sitio de un cliente. Si un cliente pide imágenes de satélite o rutas, conserva una API comercial solo para ese sitio y deja los demás en tu archivo.

Compartir este artículoservorbit.com/ma-es/blog/alojar-mapas-protomaps-pmtiles-vps

Una cartera de sitios de clientes, un solo lugar

Precios sin IVA, mostrados con su precio de renovación.