Set up a Server

Provisioning a dedicated server or virtual machine can be a cost-effective and low latency way method of serving PMTiles archives as Z/X/Y tile endpoints.

INFO

If you already use a server like nginx or Apache, you can run pmtiles serve behind a reverse proxy configuration.

Caddy

PMTiles has first-class integration with Caddy, a production-grade, dependency-free web server with automatic HTTPS. The Caddy plugin can serve buckets of archives from private S3-compatible storage, Azure, Google Cloud, public HTTP endpoints, and the filesystem.

Installation

Use Caddy Downloads to download a Caddy build with the pmtiles plugin for your OS and architecture.

Verify that the pmtiles_proxy plugin is present in your caddy executable:

caddy list-modules
...
http.handlers.pmtiles_proxy

  Non-standard modules: 1

See the Caddy docs for how to Keep Caddy Running by installing as a system service.

Caddyfile

A minimal configuration for serving a bucket:

{
  order pmtiles_proxy before reverse_proxy
}

localhost:2019 {
  handle_path /tiles/* {
    pmtiles_proxy {
      bucket https://example.com
      cache_size 256
      public_url https://localhost:2019/tiles
    }
  }
}

• handle_path: A Caddy directive that strips the prefix before passing the path to the proxy. Requires the order directive at the global Caddyfile level.
  • Example: A request to the server for /tiles/testdata.json would resolve to the file testdata.pmtiles in the bucket.
• bucket: Any bucket URL recognized by gocloud or the pmtiles cli. Examples:
  • s3://my_bucket?region=auto&endpoint=https://1234.r2.cloudflarestorage.com
• cache_size: Cache size in MB for intermediate PMTiles headers and directories. Tile data and JSON metadata are not cached.
• public_url: The base URL and path that appears in TileJSON. Required only if you need TileJSON responses. Must be the public URL as it should appear to the browser, after traversing any proxies or CDNs.

For a production-ready deployment, refer to the Caddy docs on configuring SSL and CORS headers.

Credentials

Credentials will be loaded from environment variables by the gocloud library.

• S3 buckets can specify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in Caddy's unit files:

...
[Service]
Environment=AWS_ACCESS_KEY_ID=mykey
Environment=AWS_SECRET_ACCESS_KEY=mysecret
...