TileServer GL 5.6.0

In the AWS Marketplace listing, choose Continue to Subscribe and then Continue to Configuration. Pick TileServer GL 5.6.0 on Ubuntu 24.04 as the software version, choose your Region, and choose Launch through EC2. Choose m5.large, your key pair and a security group as described in Prerequisites.

Server-side rendering uses CPU, so choose a larger instance for busy raster or static map traffic. Size the data volume to the MBTiles and PMTiles files 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=tileserver-gl}]'

Version SSH user

TileServer GL 5.6.0 on Ubuntu 24.04 ubuntu

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

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

systemctl is-active tileserver-gl nginx tileserver-gl-firstboot

active active active

TileServer GL (the node process) listens on loopback only, and nginx serves ports 80 and 443:

sudo ss -tlnp | awk 'NR==1 || /node|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:(("node")) LISTEN 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) LISTEN 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) LISTEN [::]:80 users:(("nginx"),("nginx"),("nginx")) LISTEN [::]:443 users:(("nginx"),("nginx"),("nginx"))

First boot writes this instance's URL, login and password to a root-only file. Display the file:

sudo cat /root/tileserver-gl-credentials.txt

# TileServer GL 5.6.0 on Ubuntu 24.04 (sac AWS Marketplace image)
# Written at first boot. These values are unique to this instance; keep them safe. TILESERVER_URL=https://<public-dns-name>/ TILESERVER_USERNAME=admin TILESERVER_PASSWORD=<TILESERVER_PASSWORD> TILESERVER_ACCESS=private TILESERVER_STYLE_ID=basic-preview TILESERVER_TILEJSON_URL=https://<public-dns-name>/data/v3.json TILESERVER_STYLE_URL=https://<public-dns-name>/styles/basic-preview/style.json TILESERVER_SAMPLE_TILE_URL=https://<public-dns-name>/styles/basic-preview/256/10/536/359.png
#
# Sign in at TILESERVER_URL as admin with TILESERVER_PASSWORD (the certificate is self-signed until you add your own).
# Open access (no login):
sudo tileserver-gl-access public New password:
sudo tileserver-gl-reset-password
# CORS allow-list:
sudo tileserver-gl-allow-origin add https://your-map-site.example
# Served name:
sudo tileserver-gl-set-hostname <your-dns-name>
# Your data: /var/lib/tileserver-gl/data (MBTiles/PMTiles), /etc/tileserver-gl/config.json
# Sample data licence:
cat /var/lib/tileserver-gl/DATA-LICENSES.txt ((c) OpenMapTiles (c) OpenStreetMap contributors, ODbL)
# User guide: https://secureanycloud.com/stacks/tileserver-gl-5-6-0/

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

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

Sign in as admin with the TILESERVER_PASSWORD. The front page lists every style and data source, with links to their viewers and to the GL Style, TileJSON, WMTS and XYZ service URLs.

Viewer opens the style in MapLibre GL JS, drawn in your browser from the vector tiles (the picture at the top of this guide). Raster opens the same style in Leaflet, built from PNG tiles that TileServer GL renders on the server.

Inspect on a data source shows its vector layers, color-coded, so you can see what a tile set contains.

Without a login, the server refuses every request. On the instance, the commands below read the password from the credentials file through a curl config, so it never appears on a command line. A raster tile rendered on the server is a real PNG:

curl -sk -o /dev/null -w 'without a login: HTTP %{http_code}\n' https://127.0.0.1/data/v3.json
curl -sk -K <(sudo sed -n 's/^TILESERVER_PASSWORD=\(.*\)/user = "admin:\1"/p' /root/tileserver-gl-credentials.txt) -o /tmp/tile.png -w 'rendered raster tile: HTTP %{http_code} %{content_type}, %{size_download} bytes\n' https://127.0.0.1/styles/basic-preview/256/10/536/359.png file /tmp/tile.png; rm -f /tmp/tile.png

without a login: HTTP 401 rendered raster tile: HTTP 200 image/png, 71806 bytes /tmp/tile.png: PNG image data, 256 x 256, 8-bit/color RGBA, non-interlaced

Vector tiles come straight from the MBTiles file:

curl -sk -K <(sudo sed -n 's/^TILESERVER_PASSWORD=\(.*\)/user = "admin:\1"/p' /root/tileserver-gl-credentials.txt) -o /tmp/tile.pbf -w 'vector tile: HTTP %{http_code} %{content_type}, %{size_download} bytes\n' https://127.0.0.1/data/v3/14/8580/5737.pbf rm -f /tmp/tile.pbf

vector tile: HTTP 200 application/x-protobuf, 392165 bytes

From another machine, use the full URL and your login. For example, run curl -k -u admin https://<public-dns-name>/styles/basic-preview/256/10/536/359.png -o tile.png. curl asks for the password.

Map clients read the tile URL template, zoom range, bounds and attribution from TileJSON:

curl -sk -K <(sudo sed -n 's/^TILESERVER_PASSWORD=\(.*\)/user = "admin:\1"/p' /root/tileserver-gl-credentials.txt) https://127.0.0.1/data/v3.json | python3 -c 'import json,sys; d=json.load(sys.stdin); print(json.dumps({k: d.get(k) for k in ("tilejson","name","format","minzoom","maxzoom","bounds","attribution","tiles")}, indent=2))'

{ "tilejson": "3.0.0", "name": "OpenMapTiles", "format": "pbf", "minzoom": 0, "maxzoom": 14, "bounds": [ 8.275, 47.225, 8.8, 47.533 ], "attribution": "<a href=\"https://www.openmaptiles.org/\" target=\"_blank\">&copy; OpenMapTiles</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>", "tiles": [ "https://<public-dns-name>/data/v3/{z}/{x}/{y}.pbf" ] }

The tiles URL always carries your configured host name, even when the request arrived through another address (here 127.0.0.1). A MapLibre GL JS map loads the style from https://<public-dns-name>/styles/basic-preview/style.json.

TileServer GL also draws static map images of any size, for reports and previews:

curl -sk -K <(sudo sed -n 's/^TILESERVER_PASSWORD=\(.*\)/user = "admin:\1"/p' /root/tileserver-gl-credentials.txt) -o /tmp/zurich.png -w 'static map: HTTP %{http_code} %{content_type}, %{size_download} bytes\n' 'https://127.0.0.1/styles/basic-preview/static/8.54,47.37,13/800x600.png' file /tmp/zurich.png; rm -f /tmp/zurich.png

static map: HTTP 200 image/png, 266384 bytes /tmp/zurich.png: PNG image data, 800 x 600, 8-bit/color RGBA, non-interlaced

The instance refuses writes, drops unknown host names, gives a foreign web origin no CORS grant, and walls both services off from the instance metadata service. Run these checks:

curl -sk -o /dev/null -w 'PUT: HTTP %{http_code}\n' -X PUT https://127.0.0.1/data/v3.json
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 -K <(sudo sed -n 's/^TILESERVER_PASSWORD=\(.*\)/user = "admin:\1"/p' /root/tileserver-gl-credentials.txt) -H 'Origin: https://attacker.example' https://127.0.0.1/data/v3.json | grep -ci '^access-control-allow-origin' | sed 's/^/ACAO headers for a foreign origin: /' || true systemctl show -p IPAddressDeny tileserver-gl nginx

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

Port 80 only redirects to HTTPS. Confirm the redirect:

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>/

The image starts private: every map, tile and viewer needs the login. TileServer GL has no accounts, no administration pages and no write endpoints. When you publish a basemap for your own web maps, you can open read-only access to everyone who can reach port 443. Switch the mode with these commands:

sudo tileserver-gl-access public
sudo tileserver-gl-access private

Check the current mode:

sudo tileserver-gl-access status

private

To replace the password with a new random one, run the command below. It writes the new password to /root/tileserver-gl-credentials.txt.

sudo tileserver-gl-reset-password

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 command refuses *.

sudo tileserver-gl-allow-origin add https://maps.example.com
sudo tileserver-gl-allow-origin remove https://maps.example.com

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

sudo tileserver-gl-allow-origin list

A browser on another origin does not send your login with tile requests, so cross-origin maps also need public access (Step 9). Browsers fetch cross-origin tiles only from a server whose certificate they trust, so first serve the tiles under your own DNS name and certificate (Step 11).

Point a DNS record at the instance, and then set the name that the instance serves. The command mints a new certificate for that name and pins it in nginx. It also updates every TileJSON, style and viewer URL and the credentials file (the password is kept), and it records the name so that it survives reboots.

sudo tileserver-gl-set-hostname maps.example.com

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

sudo nginx -t && sudo systemctl reload nginx

TileServer GL reads /etc/tileserver-gl/config.json. Paths are relative to the data volume /var/lib/tileserver-gl, with tile files in data/, styles in styles/ and glyphs in fonts/. Display the configuration:

cat /etc/tileserver-gl/config.json

{ "options": { "paths": { "root": "/var/lib/tileserver-gl", "fonts": "fonts", "styles": "styles", "sprites": "sprites", "icons": "icons", "files": "files", "mbtiles": "data", "pmtiles": "data" }, "allowRemoteMarkerIcons": false, "allowInlineMarkerImages": false, "serveAllStyles": false, "serveAllFonts": false }, "styles": { "basic-preview": { "style": "basic-preview/style.json", "tilejson": { "bounds": [ 8.275, 47.225, 8.8, 47.533 ] } } }, "data": { "v3": { "mbtiles": "zurich_switzerland.mbtiles" } } }

Copy your MBTiles or PMTiles file to the data folder and add it under data (for example "my-area": {"mbtiles": "my-area.mbtiles"} or {"pmtiles": "my-area.pmtiles"}). Then point a style's source at it with mbtiles://{my-area}.

The Basic preview style expects the OpenMapTiles schema, so an OpenMapTiles extract of your own region (from MapTiler or built with the OpenMapTiles tools) drops straight in under the v3 name. Then restart the service:

sudo install -o root -g root -m 0644 my-area.mbtiles /var/lib/tileserver-gl/data/ sudoedit /etc/tileserver-gl/config.json
sudo systemctl restart tileserver-gl

The full configuration reference is in the TileServer GL documentation (tileserver.readthedocs.io). Styles that name remote sources, sprites or glyphs work too, and the metadata block above stays in force for them.

To grow the data volume, resize it in EC2 and run sudo resize2fs on its device.

node -v
node -p 'require("/opt/tileserver-gl/node_modules/tileserver-gl/package.json").version' sed -n '1,9p' /usr/share/doc/tileserver-gl/BUILD-PROVENANCE.txt

v22.23.3 5.6.0 TileServer GL 5.6.0 - sac build (AWS Marketplace image) package tileserver-gl@5.6.0 from registry.npmjs.org (npm sha512 integrity in /opt/tileserver-gl/package-lock.json) lock sha256 c76c5e659ad4457ad6b8e1fae0e180437813b19645f39e618b51a87b88bb2b4e installed tileserver-gl@5.6.0 handlebars@4.7.10 morgan@1.12.1 sharp@0.35.5 tar@7.5.22 maplibre-gl@6.15.0 canvas@3.2.3 sqlite3@5.1.7 @maplibre/maplibre-gl-native@6.4.1 tileserver-gl-styles@2.0.0 express@5.2.1 runtime Node.js v22.23.3 (NodeSource node_22.x apt repository, signing key fingerprint 6F71F525282841EEDAF851B42F59B5F99B1BE0B4) dependency patches (d-102, npm overrides): handlebars 4.7.10, morgan 1.12.1, sharp 0.35.5, tar 7.5.22; node_modules/maplibre-gl 6.15.0 (copy source only; never served) npm audit --omit=dev: critical=0 high=0 moderate=0 low=5 native modules canvas 3.2.3 and sqlite3 5.1.7 compiled from source (node-gyp) against the Ubuntu 24.04 libraries;

The full provenance, including the MapLibre Native binary checksum and the viewer fix, is in /usr/share/doc/tileserver-gl/BUILD-PROVENANCE.txt. The instance also attributes the sample data and the style:

grep -A4 '^Sample map data' /var/lib/tileserver-gl/DATA-LICENSES.txt

Sample map data: /var/lib/tileserver-gl/data/zurich_switzerland.mbtiles (Zurich, Switzerland, zoom 0-14) The tileserver-gl maintainers' own quickstart dataset (GitHub release v1.3.0). (c) OpenMapTiles (https://openmaptiles.org/) (c) OpenStreetMap contributors (https://www.openstreetmap.org/copyright) OpenStreetMap data is available under the Open Database License (ODbL) v1.0: https://opendatacommons.org/licenses/odbl/1-0/ - credit "(c) OpenStreetMap contributors" wherever you show it.

Keep the (c) OpenMapTiles (c) OpenStreetMap contributors attribution whenever you serve or redisplay the sample tiles. TileServer GL shows it in its viewers and TileJSON.

The Basic preview style derives from the Mapbox Open Styles (code BSD, design CC BY 3.0), and its Noto Sans glyphs use the SIL Open Font License.