Skip to content

PMTiles File Sources

Martin can serve any type of tiles from PMTile files. A PMTiles archive can be accessed either locally or remotely via HTTP range requests, e.g. from an object storage like S3. A path to a PMTiles file may be a URL. For example:

martin  /path/to/directory   https://example.org/path/tiles.pmtiles

You may also want to generate a config file using the --save-config my-config.yaml, and later edit it and use it with --config my-config.yaml option.

Tip

See MBTiles vs PMTiles for a comparison of the two file formats.

PMTiles Hot Reload

Martin watches local directories configured under pmtiles for .pmtiles files using filesystem events, with the same add/modify/remove semantics described for MBTiles.

pmtiles:
  paths:
    - /path/to/pmtiles/directory

For remote object-storage prefixes (s3://bucket/prefix/, gs://bucket/prefix/, https://host/prefix/, etc.) Martin periodically re-lists the prefix and diffs against the previous snapshot, taking into account object ETag or Last-Modified headers to detect updates to an existing source. There is no event channel from blob storage to subscribe to. Added, updated, and removed objects propagate to the catalog.

pmtiles:
  paths:
    - s3://my-bucket/tiles/
  reload_interval: 10m  # default; set to "0s" to disable remote polling

Note

Hot reload applies to directories and remote prefixes configured under pmtiles.paths (or passed on the CLI). Named sources listed under pmtiles.sources and individual remote-file URLs are snapshotted at startup and are not watched for changes.

Serving PMTiles without a Tile Server

PMTiles archives can be served directly from HTTP range-capable storage without a dedicated tile server. This approach has several limitations:

  • Unrestricted access risk Without proper access controls, clients may download large portions (or all) of an archive, leading to significant egress costs. A tile server restricts access to tile requests, but bulk extraction remains possible via many requests, which are generally easier to detect and block.
  • Over-fetching PMTiles may fetch more data than strictly required per tile request to minimize the number of HTTP requests.
  • Lack of source composition Direct serving does not support combining PMTiles with dynamic data sources (e.g., PostGIS) into a unified tile service. A tile server (e.g, Martin) is required for this.
  • Caching behavior Cache efficiency may be reduced compared to setups with a dedicated tile server that can optimize request patterns.

Serving PMTiles from local file systems, http or Object Storage

The settings available for a PMTiles source depend on the backend:

For local sources, you need to provide the path or URL. For example:

martin  path/to/tiles.pmtiles

The available schemes are:

  • file:///path/to/my/file.pmtiles
  • path/to/my/file.pmtiles

You can also configure this via the configuration file:

pmtiles:
  sources:
    tiles: file:///path/to/my/file.pmtiles

For HTTP(s), you need to provide the url. For example:

martin  https://example.com/tiles.pmtiles

The available url schemes are:

  • http://example.com/path.pmtiles
  • https://example.com/path.pmtiles

If you want more control over your requests, you can configure additional options here as such:

pmtiles:
  allow_http: true
  sources:
    tiles: s3://bucket/path/to/tiles.pmtiles

Available http client settings

Security options

configuration description example
allow_http Allow non-TLS, i.e. non-HTTPS connections

Security warning:
If you enable this option, attackers may be able to read the data you request		 true
allow_invalid_certificates Skip certificate validation on https connections

Security warning:
You should think very carefully before using this method. If invalid certificates are trusted, any certificate for any site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort or for testing		 true

Connection options

configuration description example
user_agent User-Agent header to be used by this client martin 1.0.0
randomize_addresses Randomize order addresses that the DNS resolution yields.
This will spread the connections across more servers.		 true
connect_timeout Timeout for only the connect phase of a Client 5s
read_timeout Timeout for each read operation, reset after every successful read.
Useful for detecting stalled connections when the response size is unknown.
Disabled by default; timeout errors are retried		 30s
timeout The timeout is applied from when the request starts connecting until the response body has finished 10s
pool_idle_timeout The pool max idle timeout 5m
pool_max_idle_per_host maximum number of idle connections per host 10
http1_only Only use http1 connections false
http2_only Only use http2 connections false
http2_keep_alive_interval Interval for HTTP2 Ping frames should be sent to keep a connection alive. 15s
http2_keep_alive_timeout Timeout for receiving an acknowledgement of the keep-alive ping. 15s
http2_keep_alive_while_idle Enable HTTP2 keep alive pings for idle connections true
http2_max_frame_size Sets the maximum frame size to use for HTTP2.

Proxy settings

configuration description example
proxy_url HTTP proxy to use for requests http://proxy.example.com:8080
proxy_ca_certificate PEM-formatted CA certificate for proxy connections -----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
proxy_excludes List of hosts that bypass proxy example.com, maplibre.org

Important

Even though we name this section Amazon S3, it also works with other providers that support the S3 API, such as MinIO, Ceph, Cloudflare R2, hetzner object storage and many more.

For AWS, you need to provide the bucket name and the prefix of the object key. For example:

martin  s3://my-bucket/tiles.pmtiles

The available url schemes are:

  • s3://<bucket>/<path>
  • s3a://<bucket>/<path>
  • https://s3.<region>.amazonaws.com/<bucket>
  • https://<bucket>.s3.<region>.amazonaws.com
  • https://ACCOUNT_ID.r2.cloudflarestorage.com/bucket

If you want more control over your requests, you can configure additional options here as such:

pmtiles:
  allow_http: true
  sources:
    tiles: s3://bucket/path/to/tiles.pmtiles

Tip

All settings are also available under the aws_ prefix. This can be useful if you want to have different cloud providers.

Available AWS S3 settings

Tip

Next to the explicit configuration for auth and endpoints below, you can also use profile (for example profile: staging) to specify an AWS SDK profile. Explicit configuration overrides profiles.

AWS specific Authentication & Credentials

configuration description example
access_key_id AWS Access Key AKIAIOSFODNN7EXAMPLE
secret_access_key Secret Access Key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
session_token
token		 AWS session token used for temporary credentials IQoJb3JpZ2luX2VjEOr...
web_identity_token_file Web identity token file path for AssumeRoleWithWebIdentity /var/run/secrets/eks.amazonaws.com/serviceaccount/token
role_arn Role ARN to assume with web identity token arn:aws:iam::123456789012:role/MyWebIdentityRole
role_session_name Session name for web identity assumption my-session
endpoint_url_sts Custom STS endpoint for web identity token exchange https://sts.amazonaws.com

AWS specific Connection & Endpoint Configuration

configuration description example
region AWS region
Defaults to us-east-1		 us-west-2
bucket
bucket_name		 Bucket name my-app-bucket
endpoint
endpoint_url		 Custom S3 endpoint
Defaults to regional endpoint
Ensure consistency with virtual_hosted_style_request
By default, only HTTPS schemes are enabled; enabling HTTP can expose sensitive data
Local testing example: "http://localhost:4566"		 https://s3.us-west-2.amazonaws.com
metadata_endpoint Instance metadata endpoint (IPv4 default http://169.254.169.254)
IPv6 alternative: http://fd00:ec2::254		 http://169.254.169.254
container_credentials_relative_uri ECS container credentials relative URI /v2/credentials/12345678-1234-1234-1234-123456789012
container_credentials_full_uri EKS container credentials full URI http://169.254.170.2/v2/credentials/abc123
container_authorization_token_file Authorization token file for EKS container creds /var/run/secrets/eks.amazonaws.com/serviceaccount/token

AWS specific Request Behavior & Fallbacks

configuration description example
imdsv1_fallback Fall back to IMDSv1 if IMDSv2 is not supported (useful for older kube2iam deployments)
Security note: AWS recommends IMDSv2 only; IMDSv1 is vulnerable to SSRF attacks
Has no effect if not using instance credentials		 true
virtual_hosted_style_request Use virtual-hosted-style requests instead of path-style
Endpoint must match the style
Ensures correct bucket addressing for security and routing		 true
skip_signature Skip signing request
Security warning: Unsigned requests may expose credentials or allow tampering if endpoint is public		 true
unsigned_payload Use unsigned payload option (UNSIGNED-PAYLOAD) instead of signed
Impact: Checksums for request body are not computed in canonical requests, which can reduce integrity guarantees
Default is signed payload with checksum		 true
disable_tagging Disable tagging objects (useful if unsupported by backend) true
s3_express Enable S3 Express One Zone true
request_payer Enable S3 Requester Pays true

AWS Specific Object Integrity & Encryption

configuration description example
checksum_algorithm Checksum algorithm for uploads SHA256
server_side_encryption Type of server-side encryption:
AES256 (SSE-S3)
aws:kms (SSE-KMS)
aws:kms:dsse (DSSE-KMS)
sse-c		 AES256
sse_kms_key_id KMS Key ID for SSE-KMS or DSSE-KMS arn:aws:kms:us-east-1:123456789012:key/abcd-1234-efgh-5678
sse_bucket_key_enabled Use bucket's default KMS key (true/false) true
sse_customer_key_base64 Base64-encoded 256-bit key for SSE-C MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=

Security options

configuration description example
allow_http Allow non-TLS, i.e. non-HTTPS connections

Security warning:
If you enable this option, attackers may be able to read the data you request		 true
allow_invalid_certificates Skip certificate validation on https connections

Security warning:
You should think very carefully before using this method. If invalid certificates are trusted, any certificate for any site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort or for testing		 true

Connection options

configuration description example
user_agent User-Agent header to be used by this client martin 1.0.0
randomize_addresses Randomize order addresses that the DNS resolution yields.
This will spread the connections across more servers.		 true
connect_timeout Timeout for only the connect phase of a Client 5s
read_timeout Timeout for each read operation, reset after every successful read.
Useful for detecting stalled connections when the response size is unknown.
Disabled by default; timeout errors are retried		 30s
timeout The timeout is applied from when the request starts connecting until the response body has finished 10s
pool_idle_timeout The pool max idle timeout 5m
pool_max_idle_per_host maximum number of idle connections per host 10
http1_only Only use http1 connections false
http2_only Only use http2 connections false
http2_keep_alive_interval Interval for HTTP2 Ping frames should be sent to keep a connection alive. 15s
http2_keep_alive_timeout Timeout for receiving an acknowledgement of the keep-alive ping. 15s
http2_keep_alive_while_idle Enable HTTP2 keep alive pings for idle connections true
http2_max_frame_size Sets the maximum frame size to use for HTTP2.

Proxy settings

configuration description example
proxy_url HTTP proxy to use for requests http://proxy.example.com:8080
proxy_ca_certificate PEM-formatted CA certificate for proxy connections -----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
proxy_excludes List of hosts that bypass proxy example.com, maplibre.org

For Google Cloud, you need to provide the bucket name and the prefix of the object key. For example:

martin  gs://my-bucket/tiles.pmtiles

The available url scheme is:

  • gs://bucket/path

If you want more control over your requests, you can configure additional options here as such:

pmtiles:
  allow_http: true
  sources:
    tiles: gs://bucket/path/to/tiles.pmtiles

Tip

All settings are also available under the google_ prefix. This can be useful if you want to have different cloud providers.

Available google settings

Google specific configuration

configuration description example
base_url Sets the base URL for communicating with GCS.
If not explicitly set, it will be:
1. Derived from the service account credentials, if provided
2. Otherwise, uses the default GCS endpoint		 https://storage.googleapis.com
service_account
service_account_path		 Path to the service account file some/path/to/file
service_account_key The serialized service account key {"private_key": "private_key", "private_key_id": "private_key_id", "client_email":"client_email", "disable_oauth":true}
bucket
bucket_name		 Bucket name foobar-abc
application_credentials Set the path to the application credentials file some/path/to/file
skip_signature Skip signing request true

Security options

configuration description example
allow_http Allow non-TLS, i.e. non-HTTPS connections

Security warning:
If you enable this option, attackers may be able to read the data you request		 true
allow_invalid_certificates Skip certificate validation on https connections

Security warning:
You should think very carefully before using this method. If invalid certificates are trusted, any certificate for any site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort or for testing		 true

Connection options

configuration description example
user_agent User-Agent header to be used by this client martin 1.0.0
randomize_addresses Randomize order addresses that the DNS resolution yields.
This will spread the connections across more servers.		 true
connect_timeout Timeout for only the connect phase of a Client 5s
read_timeout Timeout for each read operation, reset after every successful read.
Useful for detecting stalled connections when the response size is unknown.
Disabled by default; timeout errors are retried		 30s
timeout The timeout is applied from when the request starts connecting until the response body has finished 10s
pool_idle_timeout The pool max idle timeout 5m
pool_max_idle_per_host maximum number of idle connections per host 10
http1_only Only use http1 connections false
http2_only Only use http2 connections false
http2_keep_alive_interval Interval for HTTP2 Ping frames should be sent to keep a connection alive. 15s
http2_keep_alive_timeout Timeout for receiving an acknowledgement of the keep-alive ping. 15s
http2_keep_alive_while_idle Enable HTTP2 keep alive pings for idle connections true
http2_max_frame_size Sets the maximum frame size to use for HTTP2.

Proxy settings

configuration description example
proxy_url HTTP proxy to use for requests http://proxy.example.com:8080
proxy_ca_certificate PEM-formatted CA certificate for proxy connections -----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
proxy_excludes List of hosts that bypass proxy example.com, maplibre.org

For Azure, you need to provide the account name, container and path. For example:

martin  az://my-container/tiles.pmtiles

The available url schemes are:

  • abfs[s]://<container>/<path> (according to fsspec)
  • abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path>
  • abfs[s]://<file_system>@<account_name>.dfs.fabric.microsoft.com/<path>
  • az://<container>/<path> (according to fsspec)
  • adl://<container>/<path> (according to fsspec)
  • azure://<container>/<path> (custom)
  • https://<account>.dfs.core.windows.net
  • https://<account>.blob.core.windows.net
  • https://<account>.blob.core.windows.net/<container>
  • https://<account>.dfs.fabric.microsoft.com
  • https://<account>.dfs.fabric.microsoft.com/<container>
  • https://<account>.blob.fabric.microsoft.com
  • https://<account>.blob.fabric.microsoft.com/<container>

If you want more control over your requests, you can configure additional options here as such:

pmtiles:
  allow_http: true
  sources:
    tiles: az://my-container/tiles.pmtiles

Tip

All settings are also available under the azure_ prefix. This can be useful if you want to have different cloud providers.

Available azure settings

Azure specific Authentication & Credentials

configuration description example
account_name Name of the Azure Storage account myaccount
access_key
account_key
master_key		 Master key for accessing the storage account

Security note:
Keep this key secret; anyone with access can read/write all data in the account		 abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9012
client_id Service principal client ID for OAuth authorization 12345678-90ab-cdef-1234-567890abcdef
client_secret Service principal client secret for OAuth authorization
Security note: Must be kept confidential		 s3cr3tV@lu3!
tenant_id
authority_id		 Tenant ID used in OAuth flows abcdef12-3456-7890-abcd-ef1234567890
authority_host Authority host used in OAuth flows https://login.microsoftonline.com/
sas_key
sas_token		 Shared Access Signature (percent-encoded)

Security note:
Grants scoped access; treat as sensitive credentials		 sv=2021-06-08&ss=b&srt=sco&sp=rwdl
&se=2025-12-31T23:59:00Z&sig=ABCDEF1234567890
bearer_token
token		 Bearer token for requests

Security note:
Token must be protected; use HTTPS		 eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
identity_endpoint
msi_endpoint		 Endpoint to request a managed identity token http://169.254.169.254/metadata/identity/oauth2/token
object_id Object ID for use with managed identity authentication 12345678-90ab-cdef-1234-567890abcdef
msi_resource_id Resource ID for managed identity authentication /subscriptions/12345678-90ab-cdef-1234-567890abcdef/
resourcegroups/myrg/providers/Microsoft.ManagedIdentity/
userAssignedIdentities/myidentity
federated_token_file File containing token for Azure AD workload identity federation /var/run/secrets/azure/federated-token
use_azure_cli Use Azure CLI for acquiring access token true

Azure specific Connection & Endpoint Configuration

configuration description example
endpoint Override endpoint used to communicate with blob storage https://myaccount.blob.core.windows.net
object_store_use_emulator
use_emulator		 Use Azurite storage emulator true
use_fabric_endpoint Use Azure Fabric endpoint (account.dfs.fabric.microsoft.com) true
container_name Container name in the storage account mycontainer

Azure specific Request Behavior & Security Options

configuration description example
skip_signature Skip signing requests

Security warning:
Unsigned requests may expose sensitive data or allow tampering; use only in secure or local environments		 true
disable_tagging Disable object tagging (useful if backend does not support it) true
fabric_token_service_url URL of Fabric token service https://fabric-token.mycompany.com
fabric_workload_host Host for Fabric workload https://workload.fabric.mycompany.com
fabric_session_token Session token for Fabric

Security note: Must be protected; use HTTPS		 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
fabric_cluster_identifier Identifier for Fabric cluster fabric-cluster-01

Security options

configuration description example
allow_http Allow non-TLS, i.e. non-HTTPS connections

Security warning:
If you enable this option, attackers may be able to read the data you request		 true
allow_invalid_certificates Skip certificate validation on https connections

Security warning:
You should think very carefully before using this method. If invalid certificates are trusted, any certificate for any site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort or for testing		 true

Connection options

configuration description example
user_agent User-Agent header to be used by this client martin 1.0.0
randomize_addresses Randomize order addresses that the DNS resolution yields.
This will spread the connections across more servers.		 true
connect_timeout Timeout for only the connect phase of a Client 5s
read_timeout Timeout for each read operation, reset after every successful read.
Useful for detecting stalled connections when the response size is unknown.
Disabled by default; timeout errors are retried		 30s
timeout The timeout is applied from when the request starts connecting until the response body has finished 10s
pool_idle_timeout The pool max idle timeout 5m
pool_max_idle_per_host maximum number of idle connections per host 10
http1_only Only use http1 connections false
http2_only Only use http2 connections false
http2_keep_alive_interval Interval for HTTP2 Ping frames should be sent to keep a connection alive. 15s
http2_keep_alive_timeout Timeout for receiving an acknowledgement of the keep-alive ping. 15s
http2_keep_alive_while_idle Enable HTTP2 keep alive pings for idle connections true
http2_max_frame_size Sets the maximum frame size to use for HTTP2.

Proxy settings

configuration description example
proxy_url HTTP proxy to use for requests http://proxy.example.com:8080
proxy_ca_certificate PEM-formatted CA certificate for proxy connections -----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
proxy_excludes List of hosts that bypass proxy example.com, maplibre.org