TileServer GL

You can start TileServer GL using the tileserver-gl command. You can specify a data file (MBTiles or PMTiles) or a configuration file. If no data file is provided, the server attempts to download a sample file (Zurich area). If no configuration file is provided, a default preview style compatible with OpenMapTiles is used.

Usage: tileserver-gl [file] [options]

Options:
  --file <file>             MBTiles or PMTiles file (local path, http(s)://, s3://, pmtiles://, or mbtiles:// URL)
  -c, --config <file>       Configuration file [config.json]
  -b, --bind <address>      Bind address
  -p, --port <port>         Port [8080]
  -C|--no-cors             Disable Cross-origin resource sharing headers
  -u|--public_url <url>    Enable exposing the server on subpaths
  --fetch-timeout <ms>      Timeout in ms for fetching remote tiles (default: 15000)
  --ignore-missing-files    Do not exit when referenced data files are missing at startup
  -V, --verbose [level]     More verbose output (level 1-3)
  -s, --silent              Less verbose output
  -l|--log_file <file>      output log file
  -f|--log_format <format>  define the log format
  -v, --version             output the version number
  -h, --help                display help for command

Use these steps only for special cases like debugging or specific environment needs. Ensure the version number in package.json, the Git tag, and the Docker image tags are identical.

1. Update Version

Manually modify the version field in package.json.

2. Create and Push Git Tag

git tag vX.X.X
git push origin --tags

3. NPM Publishing Options

Choose one of the following:

• Publish only full tileserver-gl: npm publish --access public
• Build and publish both tileserver-gl and tileserver-gl-light: node publish.js
• Build only tileserver-gl-light (no publish): node publish.js --no-publish

4. Build and Push Docker Images

Ensure you are logged in via docker login before proceeding.

Main Image:

docker buildx build --platform linux/amd64 -t maptiler/tileserver-gl:latest -t maptiler/tileserver-gl:X.X.X .
docker push maptiler/tileserver-gl --all-tags

Light Image:

cd light
docker buildx build --platform linux/amd64 -t maptiler/tileserver-gl-light:latest -t maptiler/tileserver-gl-light:X.X.X .
docker push maptiler/tileserver-gl-light --all-tags
cd ..

PMTiles can be accessed directly from AWS S3 or S3-compatible storage (e.g., MinIO, DigitalOcean Spaces) using s3:// URLs.

Supported URL Formats:

1. AWS S3: s3://bucket-name/path/to/file.pmtiles
2. S3-compatible: s3://endpoint-url/bucket-name/path/to/file.pmtiles

Authentication: TileServer-GL uses the standard AWS credential chain:

• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
• AWS credentials file: ~/.aws/credentials (Linux/macOS) or C:\Users\USERNAME\.aws\credentials (Windows)
• IAM roles (on EC2, ECS, or Lambda)

Configuration in config.json: When defining S3 sources in the data section, use configuration properties for better control. These take precedence over URL query parameters.

Using S3 in Style JSON: When referencing S3 sources inside a style JSON, you must use the pmtiles:// prefix followed by the S3 URL. You can only use URL query parameters for configuration in style JSON (properties like s3Profile are not supported here).

// Recommended: Using configuration properties in config.json
"data": {
  "us-west-tiles": {
    "pmtiles": "s3://prod-bucket/tiles.pmtiles",
    "s3Profile": "production",
    "s3Region": "us-west-2"
  }
}

// Using S3 in Style JSON (via query parameters)
"sources": {
  "aws-tiles": {
    "url": "pmtiles://s3://my-bucket/tiles.pmtiles?profile=production",
    "type": "vector"
  }
}