go-pmtiles 1.31.2

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Select go-pmtiles 1.31.2 on Ubuntu 24.04 as the software version, choose your Region, and select Launch through EC2.

Choose m5.large, your key pair and a security group as described above. go-pmtiles range-reads tiles from the archive with a small in-memory cache, so it needs little memory. Size the root volume to the archives you plan to host.

Alternatively, launch with the AWS CLI. Replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=go-pmtiles}]'

Version SSH user

go-pmtiles 1.31.2 on Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot takes a few seconds. After it completes, the three units are active:

systemctl is-active pmtiles nginx go-pmtiles-firstboot

active active active

go-pmtiles listens on loopback only, and nginx serves ports 80 and 443:

sudo ss -tlnp | awk 'NR==1 || /pmtiles|nginx/' | awk '{print $1, $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g'

State Local Peer LISTEN 127.0.0.1:8080 users:(("pmtiles")) LISTEN 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx")) LISTEN 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx")) LISTEN [::]:443 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx")) LISTEN [::]:80 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx"))

First boot writes this instance's addresses to a root-only info file. There is no password to read, because go-pmtiles is a read-only service and the only per-instance secret is the TLS private key.

sudo cat /root/go-pmtiles-info.txt

# go-pmtiles 1.31.2 on Ubuntu 24.04 (sac AWS Marketplace image)
# Written by go-pmtiles-set-hostname (first boot). go-pmtiles is a READ-ONLY map tile server: there is no
# login, no admin account and no write endpoint, so no password exists. The only per-instance secret is the
# TLS private key in /etc/ssl/go-pmtiles (self-signed, minted on this instance's first boot). GO_PMTILES_URL=https://<public-dns-name>/ GO_PMTILES_TILES_URL=https://<public-dns-name>/tiles/basemap/{z}/{x}/{y}.mvt GO_PMTILES_TILEJSON_URL=https://<public-dns-name>/tiles/basemap.json GO_PMTILES_ARCHIVE_URL=https://<public-dns-name>/data/basemap.pmtiles

The host name is your instance's public DNS name from the instance metadata service, or its public or private IP when it has no DNS name. Step 10 shows how to serve the instance under your own name.

Browse to the GO_PMTILES_URL from Step 4. The certificate is self-signed and unique to your instance, so your browser asks you to accept it once. Step 10 replaces it with your own certificate.

The bundled MapLibre viewer renders the central London basemap served by go-pmtiles, with pan, zoom, a navigation control and a scale bar. Zoom in to street level to see roads, buildings, parks, water and place labels drawn from the vector tiles.

The same tiles render anywhere in the sample extent. In this example, the map shows the Thames and the City of London.

The tiles that the viewer draws are standard Z/X/Y vector tiles. Each is a gzip-compressed Mapbox Vector Tile (.mvt). Request one and decode it to confirm that it carries real map geometry:

curl -sk -D - -o /tmp/tile.mvt https://127.0.0.1/tiles/basemap/14/8186/5448.mvt | grep -iE '^(HTTP|content-type|content-encoding)' echo "wire bytes (gzip): $(stat -c%s /tmp/tile.mvt)" echo "decoded MVT bytes: $(gzip -dc /tmp/tile.mvt | wc -c)" rm -f /tmp/tile.mvt

HTTP/2 200 content-type: application/x-protobuf content-encoding: gzip wire bytes (gzip): 83272 decoded MVT bytes: 119916

From another machine, use the full URL, for examplecurl -sk https://<public-dns-name>/tiles/basemap/14/8186/5448.mvt -o tile.mvt.

Map clients such as MapLibre, Leaflet and OpenLayers read the tile URL template, zoom range and bounds from TileJSON:

curl -sk https://127.0.0.1/tiles/basemap.json | python3 -c 'import json,sys; d=json.load(sys.stdin); print(json.dumps({k: d.get(k) for k in ("tilejson","name","minzoom","maxzoom","bounds","tiles")}, indent=2))'

{ "tilejson": "3.0.0", "name": "Protomaps Basemap", "minzoom": 0, "maxzoom": 15, "bounds": [ -0.18, 51.47, -0.05, 51.54 ], "tiles": [ "https://<public-dns-name>/tiles/basemap/{z}/{x}/{y}.mvt" ] }

The tiles URL always carries your configured host name, even when the request arrived through another address (here 127.0.0.1).

The raw archive is also served for clients that read PMTiles directly over HTTP range requests, for example the pmtiles JavaScript library. Every .pmtiles file in/var/lib/pmtiles/tiles is available at /data/<name>.pmtiles:

curl -sk -r 0-6 -o /dev/null -w 'range status: HTTP %{http_code}\n' https://127.0.0.1/data/basemap.pmtiles

range status: HTTP 206

The tile server refuses writes, unknown host names are dropped, a foreign web origin gets no CORS grant, and both services are blocked from the instance metadata service. Run these checks:

curl -sk -o /dev/null -w 'POST a tile: HTTP %{http_code}\n' -X POST https://127.0.0.1/tiles/basemap/14/8186/5448.mvt
curl -s -o /dev/null -w 'unknown Host on port 80: HTTP %{http_code} (connection closed)\n' -H 'Host: attacker.example' http://127.0.0.1/ || true
curl -sk -D - -o /dev/null -H 'Origin: https://attacker.example' https://127.0.0.1/tiles/basemap.json | grep -ci '^access-control-allow-origin' | sed 's/^/ACAO headers for a foreign origin: /' || true systemctl show -p IPAddressDeny pmtiles nginx

POST a tile: HTTP 405 unknown Host on port 80: HTTP 000 (connection closed) ACAO headers for a foreign origin: 0 IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128

Port 80 only redirects to HTTPS:

curl -s -o /dev/null -w 'http://127.0.0.1/ -> HTTP %{http_code} %{redirect_url}\n' http://127.0.0.1/

http://127.0.0.1/ -> HTTP 301 https://<public-dns-name>/

A map front end on another web origin (for example https://maps.example.com) needs a CORS grant to fetch your tiles from the browser. Add that origin to the allow-list, and nginx reloads immediately. An origin is https://host or https://host:port, with no path. The value * is refused:

sudo go-pmtiles-allow-origin add https://maps.example.com
sudo go-pmtiles-allow-origin remove https://maps.example.com

List the origins that you have added. The image ships with none, so only the instance's own HTTPS address is allowed:

sudo go-pmtiles-allow-origin list

Browsers fetch cross-origin tiles only from a server whose certificate they trust. Serve the tiles under your own DNS name and certificate (Step 10) before you point a public map site at them.

Point a DNS record at the instance, then set the name that the instance serves. This command creates a new certificate for that name, pins it in nginx, updates the TileJSON tile URLs and the info file, and records the name so that it survives reboots:

sudo go-pmtiles-set-hostname maps-tiles.example.com

To use a certificate from a public CA instead of the self-signed one, run the command above and then replace/etc/ssl/go-pmtiles/go-pmtiles.crt (full chain) and /etc/ssl/go-pmtiles/go-pmtiles.key (mode 0600, owned by root) with your own files. Then reload nginx:

sudo nginx -t && sudo systemctl reload nginx

Replace or add archives in /var/lib/pmtiles/tiles. The pmtiles command can cut a bounded extract straight from the Protomaps global basemap with range requests, so you download only your region. Pick a recent daily build from https://maps.protomaps.com/builds/:

cd /tmp pmtiles extract https://build.protomaps.com/<YYYYMMDD>.pmtiles your-area.pmtiles \
  --bbox=<min_lon>,<min_lat>,<max_lon>,<max_lat> --maxzoom=15 sudo install -o root -g root -m 0644 your-area.pmtiles /var/lib/pmtiles/tiles/
sudo systemctl restart pmtiles

Each archive is served as /tiles/<name>/{z}/{x}/{y}.mvt (TileJSON at /tiles/<name>.json) and /data/<name>.pmtiles, where <name> is the file name without .pmtiles (letters, digits, - and _). You can also build archives from your own data with pmtiles convert (from MBTiles) or the Protomaps basemaps tooling. Each extra zoom level roughly doubles the archive size, so choose --maxzoom to match how far your users zoom in. The bundled viewer always shows the sample basemap archive; point your own MapLibre, Leaflet or OpenLayers front end at your archive's TileJSON URL.

pmtiles version sed -n '1,6p' /usr/share/doc/go-pmtiles/BUILD-PROVENANCE.txt

pmtiles 1.31.2, commit a3e4951ea6a0477b784c27c1dcbfd9c130878c5a, built at 2026-10-20T08:53:20Z go-pmtiles 1.31.2 - sac source build (AWS Marketplace image) source https://github.com/protomaps/go-pmtiles/archive/refs/tags/v1.31.2.tar.gz source sha256 022386795fae441dd35927e4061daaed8cda7e21ba0a2e2253c8fd0d85bc482f (tag v1.31.2 commit a3e4951ea6a0477b784c27c1dcbfd9c130878c5a) licence BSD-3-Clause (LICENSE in this directory) toolchain go1.27.3 linux/amd64, official tarball https://go.dev/dl/go1.27.3.linux-amd64.tar.gz toolchain sha256 65efbc80fdc1fa2cd2631cad5b481777a68e8725f34e89f50fc6ac714e379b40

The full provenance (every patched dependency and the govulncheck result) is in /usr/share/doc/go-pmtiles/BUILD-PROVENANCE.txt. The sample map data and the viewer components are attributed on the instance:

grep -A3 '^Sample map data' /usr/share/doc/go-pmtiles/DATA-LICENSES.txt

The map data is an extract of OpenStreetMap, © OpenStreetMap contributors, under the Open Database License (ODbL). Keep this attribution whenever you serve or redisplay the tiles. MapLibre GL JS, the Protomaps theme and sprites are BSD-3-Clause, and the Noto Sans fonts use the SIL Open Font License.