Development

Host your own Protomaps (PMTiles) maps on a VPS

Your client wants a map on the contact page, and you plug it into a commercial API. A few months later the bill follows the site's traffic, and the key, visible in the page code, can be copied by anyone. There is a leaner way: a PMTiles archive on a VPS, served by nginx through byte-range requests and displayed by MapLibre GL JS. No map server to administer. This guide gives the commands, the real file sizes, the errors you will meet and their exact messages.

11 min read7 steps

Orbi AI agentThe contents follow the article; related articles wait at the bottom.

Contents· Why serve your own maps instead of renting tiles1/12
  1. 01Why serve your own maps instead of renting tiles
  2. 02What a PMTiles file changes
  3. 03How big it really is: planet, region, satellite
  4. 04Choosing between a keyed API, OpenFreeMap and PMTiles on your VPS
  5. 05Prerequisites to gather before you start
  6. 06Setup in seven steps
  7. 07Reading the nginx block line by line
  8. 08Behind Cloudflare: what the documentation lets you state
  9. 09Troubleshooting: the errors you actually meet
  10. 10OpenStreetMap attribution: the licence obligation
  11. 11Harden and maintain the tile server
  12. 12Plug this map server into your portfolio of sites

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

CriterionCommercial API with a keyOpenFreeMap (public instance)PMTiles on your VPS
CostPay per use, following map loadsNo fee and no key; the project covers its costs through donationsThat of your VPS and its bandwidth
Key in the pageYes, readable by any visitorNo key, no accountNo key
DependencyA vendor and its termsA public service run by a third-party projectYour server, your rules
SetupA key and a few linesA style URLOne extraction, one nginx block, one page
Satellite imageryDepends on the vendorNo: OpenStreetMap vector basemapNo: very heavy storage on your side
Pick it whenYou need imagery, geocoding or routingA prototype or a low-stakes site, with no infrastructure to runA 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

  1. Install the pmtiles command line

    It is a single binary with no dependencies, published on the releases page of the protomaps/go-pmtiles repository on GitHub. On Linux:

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

  2. Extract your region

    Pick a build listed on maps.protomaps.com/builds and give the frame as MIN_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.95

    Protomaps 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.

  3. Check the resulting archive

    pmtiles show paris.pmtiles prints the bounds, zoom levels and internal compression; pmtiles verify paris.pmtiles checks the ordering and the header. Note the internal gzip compression: it is the reason for the gzip off below.

  4. 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.

  5. Declare the nginx server

    Add this block for the subdomain, with your usual ssl_certificate lines:

    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. Reload nginx and check for the 206

    sudo nginx -t && sudo systemctl reload nginx

    Then 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.pmtiles

    You expect HTTP/2 206, content-range: bytes 0-16383/ followed by the total file size, content-length: 16384, accept-ranges: bytes and the access-control-allow-origin header. A 200 means the range was ignored: go to the troubleshooting list below.

  7. Display the map with MapLibre GL JS

    npm install maplibre-gl pmtiles @protomaps/basemaps

    Then, 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 the protomaps/basemaps-assets repository 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: http instead of https, or an extra www. Fix the value of Access-Control-Allow-Origin, and do not forget always.
  • Request header field range is not allowed by Access-Control-Allow-Headers in preflight response — the preflight does not list Range. Add it to Access-Control-Allow-Headers and answer 204 to OPTIONS requests.
  • 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 a 200 instead of a 206. Replay the curl: a proxy, a max_ranges 0 or 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 with mv, 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 404 responses on glyphs and sprite.
  • 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.

Share this articleservorbit.com/ma-en/blog/host-your-own-protomaps-pmtiles-maps-vps

A portfolio of client sites, one place

Prices shown excluding VAT, with their renewal price.