Why serve your own maps instead of renting tiles
A contact page with a map, a store locator, a delivery map: almost every client site has one. The usual reflex is to embed a commercial maps API with a key. Two problems appear over time. First the bill: it follows the number of map loads, so the site's traffic, which the agency does not control. Then the key: placed in the page code, it is readable by any visitor. Restricting it to allowed domains limits abuse without removing it, because the header that identifies the originating site can be forged from a plain script. The way out is to stop depending on a key: you host the tiles yourself, in a single file, on the server that already hosts the site.
What a PMTiles file changes
- A single archive — all the vector tiles of an area fit in one file, with no folder of millions of small images to synchronise.
- No map server — the browser reads the file through HTTP Range requests, that is, in chunks of bytes. An ordinary web server is enough.
- No key in the page — there is no secret to steal and no quota to exhaust: the map is a static resource on your own domain.
- A bill that no longer follows visits — the cost becomes that of the VPS and its bandwidth, two items you already know.
- One file per area, shared between clients — a regional extract can serve every client site located in that area.
- A free style — MapLibre GL JS is open source, and colours, labels and layers are set on the client side.
How big it really is: planet, region, satellite
The usual objection is one word: weight. The full planet basemap is around 120 GB according to the Protomaps documentation, and the build we queried reported about 140 GB. That is not what you put on a client's site, and you do not need to. The pmtiles extract tool cuts an area out of the remote archive without downloading all of it. For a frame of about 22 km by 17 km around Paris, all zoom levels included, the resulting file weighs 49 MB, and the extraction took about fifteen seconds. Each extra zoom level roughly doubles the size: the --maxzoom option is the lever if a store map does not need maximum detail.
One limit to state plainly. This file is a vector basemap: it draws the map, it does not geocode and does not compute routes. As for high-resolution satellite imagery, it remains very expensive in storage and falls outside the scope of this guide.
Choosing between a keyed API, OpenFreeMap and PMTiles on your VPS
Scroll the table
| Criterion | Commercial API with a key | OpenFreeMap (public instance) | PMTiles on your VPS |
|---|---|---|---|
| Cost | Pay per use, following map loads | No fee and no key; the project covers its costs through donations | That of your VPS and its bandwidth |
| Key in the page | Yes, readable by any visitor | No key, no account | No key |
| Dependency | A vendor and its terms | A public service run by a third-party project | Your server, your rules |
| Setup | A key and a few lines | A style URL | One extraction, one nginx block, one page |
| Satellite imagery | Depends on the vendor | No: OpenStreetMap vector basemap | No: very heavy storage on your side |
| Pick it when | You need imagery, geocoding or routing | A prototype or a low-stakes site, with no infrastructure to run | A portfolio of client sites whose bill and availability you want to control |
Prerequisites to gather before you start
A VPS whose disk is sized on your archives, plus a margin to replace a file without downtime: plan for twice the largest archive. An up-to-date nginx, or Caddy if you prefer it to handle HTTPS by itself; the comparison is in the article Caddy or Nginx on a VPS. A subdomain dedicated to tiles, with a TLS certificate: an HTTPS page loading tiles over HTTP would be blocked as mixed content. Finally a workstation with SSH access to run the pmtiles command line. Serving a static file by byte ranges is light on CPU: disk and bandwidth size the machine.
Setup in seven steps
Install the pmtiles command line
It is a single binary with no dependencies, published on the releases page of the
protomaps/go-pmtilesrepository on GitHub. On Linux:tar -xzf go-pmtiles_*_Linux_x86_64.tar.gzsudo mv pmtiles /usr/local/bin/Extract your region
Pick a build listed on
maps.protomaps.com/buildsand give the frame asMIN_LON,MIN_LAT,MAX_LON,MAX_LAT, longitude before latitude:pmtiles extract https://build.protomaps.com/YYYYMMDD.pmtiles paris.pmtiles --bbox=2.2,48.8,2.5,48.95Protomaps discourages pointing your site straight at its downloads: the extract, on the other hand, belongs to you. The source archive must be clustered, which the official builds are.
Check the resulting archive
pmtiles show paris.pmtilesprints the bounds, zoom levels and internal compression;pmtiles verify paris.pmtileschecks the ordering and the header. Note the internal gzip compression: it is the reason for thegzip offbelow.Copy the file to the VPS
rsync -avP paris.pmtiles deploy@your-vps:/var/www/tuiles/For a later update, upload the new file under another name in the same folder, then rename it with
mv.Declare the nginx server
Add this block for the subdomain, with your usual
ssl_certificatelines: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;}}}Reload nginx and check for the 206
sudo nginx -t && sudo systemctl reload nginxThen request the first 16,384 bytes, the ones the client reads before any tile:
curl -s -o /dev/null -D - -H "Origin: https://your-domain.com" -r 0-16383 https://tiles.your-domain.com/paris.pmtilesYou expect
HTTP/2 206,content-range: bytes 0-16383/followed by the total file size,content-length: 16384,accept-ranges: bytesand theaccess-control-allow-originheader. A200means the range was ignored: go to the troubleshooting list below.Display the map with MapLibre GL JS
npm install maplibre-gl pmtiles @protomaps/basemapsThen, in the page script, with an element
<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' })}});The
pmtiles://prefix goes in front of the full HTTPS URL of the file. The fonts and icons here point to the resources published by Protomaps; to depend on no one, copy theprotomaps/basemaps-assetsrepository to your server and change the two URLs.
Reading the nginx block line by line
There is no directive to switch byte ranges on: nginx handles them by itself on a static file, and the documentation only mentions max_ranges, whose value 0 turns them off. The gzip off protects those ranges: the requested bytes are those of the file as stored, and a response recompressed on the way would corrupt them; the compression is already inside the archive. The Access-Control-Allow-Headers header contains Range because the browser first sends an OPTIONS preflight request before a partial read, hence the if block that answers 204. Access-Control-Expose-Headers: ETag lets the library detect that a file was replaced. Finally, nginx inherits add_header lines from a higher level only if the current level defines none: the if block therefore repeats its own, and always sends them on error responses too.
Behind Cloudflare: what the documentation lets you state
A maps file behind a proxy misbehaves if you ignore three rules, all taken from the Cloudflare documentation. The .pmtiles extension is not in the list of extensions cached by default: without a cache rule, the file is read from your origin every time. The maximum size of a cached file is 512 MB on the Free, Pro and Business plans: a regional extract fits, a planet archive does not. And a 206 response is cached only if it is not encoded, with a consistent Content-Range. Check the outcome with the cf-cache-status header. Zone settings of this kind are detailed in Cloudflare for a client site. A DNS-only subdomain avoids the question, at the price of an exposed origin IP: decide it with the rest of your portfolio.
Troubleshooting: the errors you actually meet
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource— the header is missing or the origin does not match exactly:httpinstead ofhttps, or an extrawww. Fix the value ofAccess-Control-Allow-Origin, and do not forgetalways.Request header field range is not allowed by Access-Control-Allow-Headers in preflight response— the preflight does not listRange. Add it toAccess-Control-Allow-Headersand answer204toOPTIONSrequests.Server returned no content-length header or content-length exceeding request. Check that your storage backend supports HTTP Byte Serving.— the server returned the whole file with a200instead of a206. Replay thecurl: a proxy, amax_ranges 0or compression on the way are the causes.Wrong magic number for PMTiles archive— what the client receives is not a PMTiles archive: an HTML error page, a wrong path, or a file truncated by an interrupted upload. Compare the size on the server and on your workstation.Server returned non-matching ETag … after one retry— the file changed during reading, or two versions are mixed in a cache. Replace the file withmv, never with an in-place copy.- Blank map, background with no labels or roads — fonts or icons are not loading: open the network tab and look for
404responses onglyphsandsprite. - No OpenStreetMap credit on screen — the map renders, but the licence is not respected. See the next section.
OpenStreetMap attribution: the licence obligation
The data comes from OpenStreetMap, published under the ODbL licence. The Protomaps basemap is distributed as a Produced Work under that licence, with attribution to OpenStreetMap required. OpenStreetMap asks you to credit the project and to state that the data is under the ODbL, for example with a link to openstreetmap.org/copyright. In MapLibre, the attribution field of the source appears in the corner of the map: keep it visible, and do not hide this control in a client's stylesheet. No error reports the omission, which makes it easy to ship without noticing.
Harden and maintain the tile server
Allow one exact origin, never *: Protomaps recommends giving your own domain. For several client sites, replace the fixed value with a map $http_origin that only returns the domains of a list. Watch the subdomain's bandwidth in your nginx logs: it is now your cost item. Schedule the extraction at regular intervals, to a temporary file, then mv.
Plug this map server into your portfolio of sites
Because the archive is a static file, a single tiles subdomain can serve the maps of all the client sites in one area: one file, one certificate, one backup. It naturally lives on the VPS that already hosts your sites, which avoids one more vendor to follow; the choice between VPS and shared hosting is covered in Shared hosting or VPS for an agency client site. If a client asks for satellite imagery or routing, keep a commercial API for that site alone, and leave the others on your archive.
servorbit.com/ma-en/blog/host-your-own-protomaps-pmtiles-maps-vps
