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
| Criterio | API comercial con clave | OpenFreeMap (instancia pública) | PMTiles en tu VPS |
|---|---|---|---|
| Coste | Por uso, sigue las cargas de mapa | Sin tarifa ni clave; el proyecto cubre sus costes con donaciones | El de tu VPS y su ancho de banda |
| Clave en la página | Sí, legible por cualquier visitante | Sin clave ni cuenta | Sin clave |
| Dependencia | Un proveedor y sus condiciones | Un servicio público mantenido por un proyecto externo | Tu servidor, tus reglas |
| Puesta en marcha | Una clave y unas líneas | Una URL de estilo | Una extracción, un bloque nginx, una página |
| Imágenes de satélite | Según el proveedor | No: mapa base vectorial de OpenStreetMap | No: almacenamiento muy pesado a tu cargo |
| Elígelo cuando | Necesitas imágenes, geocodificación o rutas | Un prototipo o un sitio de poca importancia, sin infraestructura que mantener | Una 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
Instalar la línea de comandos pmtiles
Es un binario único, sin dependencias, publicado en la página de versiones del repositorio
protomaps/go-pmtilesen GitHub. En Linux:tar -xzf go-pmtiles_*_Linux_x86_64.tar.gzsudo mv pmtiles /usr/local/bin/Extraer tu región
Elige una build listada en
maps.protomaps.com/buildse indica el encuadre con el formatoMIN_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.95Protomaps 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.
Comprobar el archivo obtenido
pmtiles show paris.pmtilesmuestra los límites, los niveles de zoom y la compresión interna;pmtiles verify paris.pmtilescomprueba el orden y la cabecera. Fíjate en la compresión interna gzip: es la razón delgzip offmás abajo.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.Declarar el servidor nginx
Añade este bloque para el subdominio, con tus líneas
ssl_certificatehabituales: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;}}}Recargar nginx y comprobar el 206
sudo nginx -t && sudo systemctl reload nginxPide 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.pmtilesSe espera
HTTP/2 206,content-range: bytes 0-16383/seguido del tamaño total del archivo,content-length: 16384,accept-ranges: bytesy la cabeceraaccess-control-allow-origin. Un200indica que se ignoró el rango: pasa a la lista de solución de errores más abajo.Mostrar el mapa con MapLibre GL JS
npm install maplibre-gl pmtiles @protomaps/basemapsDespué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 repositorioprotomaps/basemaps-assetsa 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:httpen lugar dehttps, o unwwwde más. Corrige el valor deAccess-Control-Allow-Origin, sin olvidaralways.Request header field range is not allowed by Access-Control-Allow-Headers in preflight response— el preflight no citaRange. Añádelo aAccess-Control-Allow-Headersy responde204a las peticionesOPTIONS.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 un200en lugar de un206. Repite elcurl: un proxy, unmax_ranges 0o 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 conmv, 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
404englyphsysprite. - 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.
servorbit.com/ma-es/blog/alojar-mapas-protomaps-pmtiles-vps
