Martin Tile Server

https://maplibre.org/martin/
Admin
Martin is a fast tile server written in Rust that generates and serves vector tiles on the fly from...
Tokens:39,985
Snippets:527
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Quick Start Development Setup

Source: https://maplibre.org/martin/development

Initial installation of tools and starting the development environment.

```bash
# Install tools
cargo install just --locked
just validate-tools

# Start development
just start  # test database
just run    # Martin server
just test   # verify setup
```

--------------------------------

### Validate and Start Development Environment

Source: https://maplibre.org/martin/getting-involved

Use these commands to verify that all necessary tools are installed and to initialize the test database.

```bash
# Validate all required tools are installed
just validate-tools

# Start the development environment
just start  # starts test database
just help   # shows common commands
```

--------------------------------

### Install and Verify Just

Source: https://maplibre.org/martin/development

Commands to install the Just command runner and verify the development environment setup.

```bash
cargo install just --locked
just validate-tools  # verify setup
```

--------------------------------

### Initialize and run Martin on Windows

Source: https://maplibre.org/martin/quick-start-windows

Commands to verify SQLite installation, initialize the database from SQL, and start the Martin server.

```bash
# Check if sqlite is installed
sqlite3 --version

# Initialize a database
sqlite3 world_cities.mbtiles < world_cities.sql

# Show Martin help screen
martin --help

# Run Martin with the sample data as the only tile source
martin world_cities.mbtiles
```

--------------------------------

### Install Martin via cargo-binstall

Source: https://maplibre.org/martin/installation

Install the pre-built binary using the cargo-binstall tool.

```bash
cargo install cargo-binstall
cargo binstall martin
martin --help
```

--------------------------------

### Start Docker Compose

Source: https://maplibre.org/martin/pg-ssl-certificates

Command to launch the configured PostgreSQL container.

```bash
docker compose up
```

--------------------------------

### Configure PostgreSQL Connections

Source: https://maplibre.org/martin/config-file

Example of defining a list of PostgreSQL database configurations.

```yaml
postgres:
  - connection_string:  postgres://postgres:postgres@localhost:5432/db
    default_srid: 4326
  - connection_string:  postgres://postgres:postgres@another_host:5432/another_db
    default_srid: 3857
```

--------------------------------

### Start Martin service

Source: https://maplibre.org/martin/run-with-docker-compose

Starts the Martin container once the database is ready.

```bash
docker compose up -d martin
```

--------------------------------

### Start Martin with a configuration file

Source: https://maplibre.org/martin/config-file

Use the --config argument to specify the path to your YAML configuration file.

```bash
martin --config config.yaml
```

--------------------------------

### Install Martin with COG support

Source: https://maplibre.org/martin/sources-cog-files

Install Martin from source with the unstable COG feature enabled.

```bash
cargo install martin --features=unstable-cog
```

--------------------------------

### Start database service

Source: https://maplibre.org/martin/run-with-docker-compose

Initializes the database container in detached mode.

```bash
docker compose up -d db
```

--------------------------------

### Install Martin via Homebrew

Source: https://maplibre.org/martin/installation

Install Martin on macOS using the official Homebrew tap.

```bash
brew tap maplibre/martin
brew install martin
martin --help
```

--------------------------------

### Initialize and run Martin with demo data

Source: https://maplibre.org/martin/quick-start-macos

Commands to initialize the SQLite database, display help, and start the Martin server with a sample MBTiles file.

```bash
# Initialize a database
sqlite3 world_cities.mbtiles < world_cities.sql

# Show Martin help screen
./martin --help

# Run Martin with the sample data as the only tile source
./martin world_cities.mbtiles
```

--------------------------------

### Azure PMTiles Connection Example

Source: https://maplibre.org/martin/sources-pmtiles

Basic syntax for connecting to a PMTiles file stored in an Azure container.

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

--------------------------------

### Example YAML configuration file

Source: https://maplibre.org/martin/config-file

A sample configuration file structure including the schema reference and base path setting.

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/maplibre/martin/main/schemas/config.json

# Set `TileJSON` URL path prefix.
# This overrides the default path prefix for URLs in `TileJSON` responses.
# If both `route_prefix` and `base_path` are set, `base_path` takes priority for `TileJSON` URLs.
# If neither is set, the `X-Rewrite-URL` header is respected.
# Must begin with a `/`.
# Examples: `/`, `/tiles`
base_path: null
```

--------------------------------

### Define Martin configuration settings

Source: https://maplibre.org/martin/config-file

Example configuration file demonstrating global, source-type, and per-source encoder settings.

```yaml
# Global: default encoder settings for any source whose tiles get converted
convert_to_mlt: auto
convert_to_mvt: auto

postgres:
  connection_string: postgresql://localhost/mydb
  # Source-type: override the encoder config for all PG sources
  convert_to_mlt: auto
  tables:
    my_table:
      # Per-source: this table uses the default MLT encoder config
      convert_to_mlt: auto
    no_mlt_table:
      # Per-source: explicitly opt out
      # Even if the client requests MLT, this source is served as MVT.
      convert_to_mlt: disabled
mbtiles: # gets global default
  - some/file.mbtiles
```

--------------------------------

### Install Martin via Debian package

Source: https://maplibre.org/martin/installation

Manually download and install the Debian package for x86_64 systems.

```bash
curl -O https://github.com/maplibre/martin/releases/latest/download/debian-x86_64.deb
sudo dpkg -i ./debian-x86_64.deb
martin --help
rm ./debian-x86_64.deb
```

--------------------------------

### Serve Tiles with Martin

Source: https://maplibre.org/martin/recipe-basemap-postgis

Starts the Martin server to serve MBTiles and PostGIS data from the specified connection string.

```bash
martin data/monaco.mbtiles postgres://postgres:mypass@localhost:5432/postgres
```

--------------------------------

### Configure function postprocessing

Source: https://maplibre.org/martin/sources-pg-functions

Example configuration for enabling automatic tile postprocessing for a specific PostgreSQL function.

```yaml
postgres:
  connection_string: postgresql://localhost/mydb
  functions:
    my_function:
      convert_to_mlt: auto
      convert_to_mvt: auto
```

--------------------------------

### Advanced PMTiles Configuration

Source: https://maplibre.org/martin/sources-pmtiles

Example of configuring PMTiles sources with additional options such as allowing HTTP connections.

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

--------------------------------

### Run PostGIS Container

Source: https://maplibre.org/martin/recipe-basemap-postgis

Starts a PostGIS instance using Docker with a specified password and port mapping.

```bash
docker run \
  --name some-postgis \
  --env POSTGRES_PASSWORD=mypass \
  --publish 5432:5432 \
  --detach \
  postgis/postgis
```

--------------------------------

### Configure VirtualHost for Martin

Source: https://maplibre.org/martin/run-with-apache

Example configuration for proxying requests to a local Martin instance on port 3000.

```apache
<VirtualHost *:443>
    ServerName mydomain.tld
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/mydomain
    ProxyPreserveHost On

    RewriteEngine on
    RewriteCond %{REQUEST_URI} ^/tiles/(.*)$
    RewriteRule ^/tiles/(.*)$ http://localhost:3000/tiles/$1 [P,L]

    <IfModule mod_headers.c>
        RequestHeader set X-Forwarded-Proto "https"
    </IfModule>

    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
</VirtualHost>
```

--------------------------------

### Catalog Response Example

Source: https://maplibre.org/martin/using

A sample JSON response structure returned by the catalog endpoint.

```json
{
  "tiles" {
    "function_zxy_query": {
      "name": "public.function_zxy_query",
      "content_type": "application/x-protobuf"
    },
    "points1": {
      "name": "public.points1.geom",
      "content_type": "image/webp"
    },
    ...
  },
  "sprites": {
    "cool_icons": {
      "images": [
        "bicycle",
        "bear",
      ]
    },
    ...
  },
  "fonts": {
    "Noto Mono Regular": {
      "family": "Noto Mono",
      "style": "Regular",
      "glyphs": 875,
      "start": 0,
      "end": 65533
    },
    ...
  },
  "styles": {
    "maplibre_demo": {
      "path": "path/to/maplibre_demo.json",
    },
  },
}
```

--------------------------------

### Update Existing Git Repository Setup

Source: https://maplibre.org/martin/development

Commands to reconfigure an existing local clone to follow the recommended upstream/origin remote structure.

```bash
# Getting a quick glance about your remotes: git remote -v
git remote -v
# Rename the existing remote to "upstream". Your "main" branch will now track "upstream/main"
git remote rename origin upstream

# Add your own fork as a remote, naming it "origin" (adjust the URL)
git remote add origin https://github.com/nyurik/martin.git
```

--------------------------------

### Example TileJSON manifest

Source: https://maplibre.org/martin/sources-pg-tables

The default TileJSON structure generated by Martin for a table source.

```json
{
    "tilejson": "3.0.0",
    "tiles": [
        "http://localhost:3000/table_source/{z}/{x}/{y}"
    ],
    "vector_layers": [
        {
            "id": "table_source",
            "fields": {
                "gid": "int4"
            }
        }
    ],
    "bounds": [
        -2.0,
        -1.0,
        142.84131509869133,
        45.0
    ],
    "description": "public.table_source.geom",
    "name": "table_source"
}
```

--------------------------------

### Define a PostgreSQL table for vector tiles

Source: https://maplibre.org/martin/sources-pg-tables

Example SQL schema for a table that Martin can publish as a vector tile source.

```sql
CREATE TABLE "public"."table_source" (
  "gid" int4 NOT NULL,
  "geom" "public"."geometry"
);
```

--------------------------------

### Define Martin Configuration

Source: https://maplibre.org/martin/run-with-lambda

Example YAML configuration file for defining PMTiles sources within the Lambda function.

```yaml
pmtiles:
  sources:
    demotiles: <url to a pmtiles file>
```

--------------------------------

### GET /catalog

Source: https://maplibre.org/martin/using

Retrieves a list of all available sources including tiles, sprites, fonts, and styles.

```APIDOC
## GET /catalog

### Description
Returns a list of all available sources currently served by Martin.

### Method
GET

### Endpoint
/catalog

### Response
#### Success Response (200)
- **tiles** (object) - Map of available tile sources
- **sprites** (object) - Map of available sprite sources
- **fonts** (object) - Map of available font sources
- **styles** (object) - Map of available style sources
```

--------------------------------

### Run Maputnik locally with Docker

Source: https://maplibre.org/martin/recipe-basemap-postgis

Starts a local instance of Maputnik on port 8888 to bypass CORS restrictions.

```bash
docker run -it --rm -p 8888:80 ghcr.io/maplibre/maputnik:main
```

--------------------------------

### Configure Fonts via CLI

Source: https://maplibre.org/martin/sources-fonts

Specify font files or directories using the --font parameter when starting Martin.

```bash
martin --font /path/to/font/file.ttf --font /path/to/font_dir
```

--------------------------------

### GET /style/{style_id}/static/{camera}/{size}.{ext}

Source: https://maplibre.org/martin/sources-styles/rendering

Renders a static image of the base map style at the specified camera position and dimensions.

```APIDOC
## GET /style/{style_id}/static/{camera}/{size}.{ext}

### Description
Returns a static image (PNG, JPEG, or WebP) of the base map style at a chosen camera view.

### Method
GET

### Endpoint
/style/{style_id}/static/{camera}/{size}.{ext}

### Parameters
#### Path Parameters
- **style_id** (string) - Required - The ID of the style to render.
- **camera** (string) - Required - Camera configuration: 'lon,lat,zoom', 'lon,lat,zoom@bearing', 'lon,lat,zoom@bearing,pitch', or 'minLon,minLat,maxLon,maxLat'.
- **size** (string) - Required - Dimensions in format 'WIDTHxHEIGHT[@{scale}x]'. Max 2048px, max 4x scale.
- **ext** (string) - Required - Image format: 'png', 'jpg', or 'webp'.
```

--------------------------------

### Configuration and Initialization Flow

Source: https://maplibre.org/martin/architecture

Describes the startup process, including argument parsing, source discovery, and server route registration.

```mermaid
sequenceDiagram
    participant CLI
    participant Config as Config Parser
    participant Discovery as Source Discovery
    participant Sources as Tile Sources
    participant Server as HTTP Server

    CLI->>Config: Parse args & config file
    Config->>Discovery: Initialize sources

    alt PostgreSQL Source
        Discovery->>Discovery: Connect to database
        Discovery->>Discovery: Query tables & functions
        Discovery->>Sources: Register table sources
        Discovery->>Sources: Register function sources
    end

    alt File Sources
        Discovery->>Discovery: Scan MBTiles files
        Discovery->>Discovery: Scan PMTiles files
        Discovery->>Sources: Register file sources
    end

    Sources-->>Server: Source catalog
    Server->>Server: Setup routes
    Server->>Server: Start HTTP listener
```

--------------------------------

### Initialize and run Martin on Linux

Source: https://maplibre.org/martin/quick-start-linux

Commands to prepare the environment, initialize a SQLite database, and execute the Martin binary.

```bash
mkdir martin
cd martin

# Download some sample data
curl -L -O https://github.com/maplibre/martin/raw/main/tests/fixtures/mbtiles/world_cities.sql

# Check if sqlite is installed
sqlite3 --version

# Initialize a database
sqlite3 world_cities.mbtiles < world_cities.sql

# Download the latest version of Martin binary, extract it, and make it executable
curl -L -O https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz
tar -xzf martin-x86_64-unknown-linux-gnu.tar.gz
chmod +x ./martin

# Show Martin help screen
./martin --help

# Run Martin with the sample data as the only tile source
./martin world_cities.mbtiles
```

--------------------------------

### GET /font/{name}/{start}-{end}

Source: https://maplibre.org/martin/sources-fonts

Retrieves a glyph range for a specific font. Font names must be URL-escaped.

```APIDOC
## GET /font/{name}/{start}-{end}

### Description
Retrieves glyph ranges for a single font. The font name must match the name in the catalog and be URL-escaped.

### Method
GET

### Endpoint
/font/{name}/{start}-{end}

### Parameters
#### Path Parameters
- **name** (string) - Required - The case-sensitive name of the font.
- **start** (integer) - Required - The start of the glyph range.
- **end** (integer) - Required - The end of the glyph range.
```

--------------------------------

### GET /font/{name1},...,{nameN}/{start}-{end}

Source: https://maplibre.org/martin/sources-fonts

Retrieves a glyph range using multiple fonts with fallback support.

```APIDOC
## GET /font/{name1},...,{nameN}/{start}-{end}

### Description
Retrieves a glyph range by combining multiple fonts. Glyphs are taken from the first font if available, falling back to subsequent fonts if not found.

### Method
GET

### Endpoint
/font/{name1},...,{nameN}/{start}-{end}

### Parameters
#### Path Parameters
- **name1...nameN** (string) - Required - A comma-separated list of font names.
- **start** (integer) - Required - The start of the glyph range.
- **end** (integer) - Required - The end of the glyph range.
```

--------------------------------

### Sprite JSON Index Example

Source: https://maplibre.org/martin/sources-sprites

Example structure of the metadata index describing image positions and dimensions within a sprite.

```json
{
  "bicycle": {
    "height": 15,
    "pixelRatio": 1,
    "width": 15,
    "x": 20,
    "y": 16
  },
  ...
}
```

--------------------------------

### Just Command Overview

Source: https://maplibre.org/martin/development

Common commands for listing and validating the project environment.

```bash
just help        # common commands
just --list      # all commands
just validate-tools  # check setup
```

--------------------------------

### GET /health

Source: https://maplibre.org/martin/using

Checks the health status of the Martin server.

```APIDOC
## GET /health

### Description
Returns the health status of the Martin server.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Returns 'OK'
```

--------------------------------

### GET /catalog

Source: https://maplibre.org/martin/sources-fonts

Retrieves a list of all available fonts and their metadata.

```APIDOC
## GET /catalog

### Description
Returns a JSON object containing all available fonts and their associated metadata including family, style, and glyph range.

### Method
GET

### Endpoint
/catalog

### Response
#### Success Response (200)
- **fonts** (object) - A map of font names to their metadata.
```

--------------------------------

### View martin-cp help documentation

Source: https://maplibre.org/martin/martin-cp

Displays the full list of available arguments and options for the martin-cp utility.

```bash
A tool to bulk copy tiles from any Martin-supported sources into an mbtiles file

Usage: martin-cp [OPTIONS] --output-file <OUTPUT_FILE> [CONNECTION]...

Arguments:
  [CONNECTION]...
          Connection strings, e.g. postgres://... or /path/to/files

Options:
  -s, --source <SOURCE>
          Name of the source to copy from. Not required if there is only one source

  -o, --output-file <OUTPUT_FILE>
          Path to the mbtiles file to copy to

      --mbtiles-type <SCHEMA>
          Output format of the new destination file. Ignored if the file exists. [DEFAULT: normalized]

          [possible values: flat, flat-with-hash, normalized]

      --url-query <URL_QUERY>
          Optional query parameter (in URL query format) for the sources that support it (e.g. Postgres functions).

      --encoding <ENCODING>
          Optional accepted encoding parameter as if the browser sent it in the HTTP request.

          If set to multiple values like gzip,br, martin-cp will use the first encoding, or re-encode if the tile is already encoded and that encoding is not listed. Use identity to disable compression. Ignored for non-encodable tiles like PNG and JPEG.

          [default: gzip]

      --on-duplicate <ON_DUPLICATE>
          Allow copying to existing files, and indicate what to do if a tile with the same Z/X/Y already exists.

          [possible values: override, ignore, abort]

      --concurrency <CONCURRENCY>
          Number of concurrent connections to use

          [default: 1]

      --bbox <BBOX>
          Bounds to copy, in the format min_lon,min_lat,max_lon,max_lat. Can be specified multiple times with overlapping bounds being handled correctly. Maximum bounds follows mbtiles specification for xyz-compliant tile bounds

          If omitted, will first default to configured source bounds if present. Otherwise, will default to global xyz-compliant tile bounds.

          [default: -180,-85.05112877980659,180,85.0511287798066]

      --min-zoom <MIN_ZOOM>
          Minimum zoom level to copy

      --max-zoom <MAX_ZOOM>
          Maximum zoom level to copy

  -z, --zoom-levels <ZOOM_LEVELS>
          List of zoom levels to copy

      --skip-agg-tiles-hash
          Skip generating a global hash for mbtiles validation. By default, martin-cp will compute and update agg_tiles_hash metadata value

      --set-meta <KEY=VALUE>
          Set additional metadata values. Must be set as "key=value" pairs. Can be specified multiple times

  -c, --config <CONFIG>
          Path to config file. If set, no tile source-related parameters are allowed

      --save-config <SAVE_CONFIG>
          Save resulting config to a file or use "-" to print to stdout. By default, only print if sources are auto-detected

  -b, --auto-bounds <AUTO_BOUNDS>
          Specify how bounds should be computed for the spatial PG tables. [DEFAULT: quick]

          Possible values:
          - quick: Compute table geometry bounds, but abort if it takes longer than 5 seconds
          - calc:  Compute table geometry bounds. The startup time may be significant. Make sure all GEO columns have indexes
          - skip:  Skip bounds calculation. The bounds will be set to the whole world

      --ca-root-file <CA_ROOT_FILE>
          Loads trusted root certificates from a file. The file should contain a sequence of PEM-formatted CA certificates

  -d, --default-srid <DEFAULT_SRID>
          If a spatial PG table has SRID 0, then this default SRID will be used as a fallback

  -p, --pool-size <POOL_SIZE>
          Maximum Postgres connections pool size [DEFAULT: 20]

  -m, --max-feature-count <MAX_FEATURE_COUNT>
          Limit the number of geo features per tile.

          If the source table has more features than set here, they will not be included in the tile and the result will look "cut off"/incomplete. This feature allows to put a maximum latency bound on tiles with extreme amount of detail at the cost of
          not returning all data. It is sensible to set this limit if you have user generated/untrusted geodata, e.g. a lot of data points at Null Island.

          Can be either a positive integer or unlimited if omitted.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Use RUST_LOG environment variable to control logging level, e.g. RUST_LOG=debug or RUST_LOG=martin_cp=debug. See https://docs.rs/env_logger/latest/env_logger/index.html#enabling-logging for more information.
```

--------------------------------

### Prepare Lambda Layer

Source: https://maplibre.org/martin/run-with-lambda

Download the Martin binary and prepare the directory structure for an AWS Lambda layer.

```bash
mkdir -p martin_layer/src/bin/
cd martin_layer
curl -OL https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-unknown-linux-musl.tar.gz
tar -C src/bin/ -xzf martin-aarch64-unknown-linux-musl.tar.gz martin
```

--------------------------------

### Build Martin from source

Source: https://maplibre.org/martin/installation

Compile Martin from source code using Cargo.

```bash
cargo install martin --locked
martin --help
```

--------------------------------

### GET /{sourceID}

Source: https://maplibre.org/martin/using

Retrieves the TileJSON metadata for a specific source or composite source.

```APIDOC
## GET /{sourceID}

### Description
Returns the TileJSON metadata for the specified source ID. Composite sources can be requested by comma-separating IDs (e.g., /source1,source2).

### Method
GET

### Endpoint
/{sourceID}

### Parameters
#### Path Parameters
- **sourceID** (string) - Required - The unique identifier of the source or a comma-separated list of source IDs.
```

--------------------------------

### Default TileJSON Manifest

Source: https://maplibre.org/martin/sources-pg-functions

Example of the automatically generated TileJSON manifest for a PostgreSQL function.

```json
{
  "tilejson": "3.0.0",
  "tiles": [
    "http://localhost:3111/function_zxy_query_jsonb/{z}/{x}/{y}"
  ],
  "name": "function_zxy_query_jsonb",
  "description": "public.function_zxy_query_jsonb"
}
```

--------------------------------

### Create Lambda Bootstrap File

Source: https://maplibre.org/martin/run-with-lambda

Create the required bootstrap executable that invokes the Martin binary with a configuration file.

```bash
cat <<EOF >src/bootstrap
#!/bin/sh
set -eu
exec martin --config \${_HANDLER}.yaml
EOF
```

--------------------------------

### GET /style/<style_id>

Source: https://maplibre.org/martin/sources-styles

Retrieves the JSON content for a specific style identified by its ID.

```APIDOC
## GET /style/<style_id>

### Description
Retrieves the JSON content for the specified style. Changes or removals of styles are reflected immediately, but additions require a server restart.

### Method
GET

### Endpoint
/style/<style_id>

### Parameters
#### Path Parameters
- **style_id** (string) - Required - The unique identifier of the style to retrieve.
```

--------------------------------

### Serve Tiles via CLI

Source: https://maplibre.org/martin/sources-files

Run Martin by specifying paths to local files, directories, or remote PMTiles URLs.

```bash
martin  /path/to/mbtiles/file.mbtiles  /path/to/directory   https://example.org/path/tiles.pmtiles
```

--------------------------------

### Running Sub-project Recipes

Source: https://maplibre.org/martin/development

Executing namespaced commands for the Web UI and Demo sub-projects from the repository root.

```bash
# Web UI (martin/martin-ui/)
just ui::test        # run frontend tests
just ui::biome       # run BiomeJS formatter and linter
just ui::type-check  # TypeScript type checking

# Demo (demo/)
just demo::up        # start the demo with Docker Compose
just demo::build     # build demo Docker images
```

--------------------------------

### GET /{sourceID}/{z}/{x}/{y}

Source: https://maplibre.org/martin/using

Retrieves map tiles for a specific source or composite source.

```APIDOC
## GET /{sourceID}/{z}/{x}/{y}

### Description
Fetches map tiles for the specified source at the given zoom level and coordinates.

### Method
GET

### Endpoint
/{sourceID}/{z}/{x}/{y}

### Parameters
#### Path Parameters
- **sourceID** (string) - Required - The unique identifier of the source or a comma-separated list of source IDs.
- **z** (integer) - Required - Zoom level.
- **x** (integer) - Required - X coordinate.
- **y** (integer) - Required - Y coordinate.
```

--------------------------------

### Initialize Git Repository with Forks

Source: https://maplibre.org/martin/development

Commands to clone the primary repository and configure a personal fork as the origin remote.

```bash
# clone the primary fork to your local machine, naming the remote "upstream"
# make sure to replace the URL with the correct one
git clone -o upstream https://github.com/maplibre/martin.git
cd martin

# add your own fork as a remote, naming it "origin"
git remote add origin https://github.com/nyurik/martin.git
```

--------------------------------

### GET /catalog

Source: https://maplibre.org/martin/sources-styles

Retrieves a list of all available style IDs currently served by the Martin instance.

```APIDOC
## GET /catalog

### Description
Returns a list of all available `<style_id>`s currently served by the Martin server.

### Method
GET

### Endpoint
/catalog
```

--------------------------------

### Display mbtiles help menu

Source: https://maplibre.org/martin/mbtiles

Displays the list of available commands and options for the mbtiles utility.

```bash
A utility to work with .mbtiles file content

Usage: mbtiles <COMMAND>

Commands:
  summary      Show MBTiles file summary statistics
  meta-all     Prints all values in the metadata table in a free-style, unstable YAML format
  meta-get     Gets a single value from the MBTiles metadata table
  meta-set     Sets a single value in the MBTiles metadata table or deletes it if no value
  diff         Compare two files A and B, and generate a new diff file. If the diff file is applied to A, it will produce B
  copy         Copy tiles from one mbtiles file to another
  apply-patch  Apply diff file generated from 'copy' command
  meta-update  Update metadata to match the content of the file
  validate     Validate tile data if hash of tile data exists in file
  pack         Pack a directory tree of tiles into an MBTiles file
  cache-purge  Remove expired entries from a tile-cache MBTiles file (see the cache schema), and optionally evict entries to bound the file size
  unpack       Unpack an MBTiles file into a directory tree of tiles
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Use RUST_LOG environment variable to control logging level, e.g. RUST_LOG=debug or RUST_LOG=mbtiles=debug. See https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html for more information.
```

--------------------------------

### Configure Martin with Heroku Environment Variables

Source: https://maplibre.org/martin/recipes

Set the required SSL environment variables and database URL before launching Martin.

```bash
export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME)
export PGSSLCERT=DIRECTORY/PREFIXpostgresql.crt
export PGSSLKEY=DIRECTORY/PREFIXpostgresql.key
export PGSSLROOTCERT=DIRECTORY/PREFIXroot.crt

martin
```

--------------------------------

### Deploy Martin with NGINX using Docker Compose

Source: https://maplibre.org/martin/run-with-nginx

A sample docker-compose.yml file to orchestrate Martin, NGINX, and a PostgreSQL database.

```yaml
services:
  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "80:80"
    volumes:
      - ./cache:/var/cache/nginx
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - martin

  martin:
    image: ghcr.io/maplibre/martin:1.12.0
    restart: unless-stopped
    environment:
      - DATABASE_URL=postgres://postgres:password@db/db
    depends_on:
      - db

  db:
    image: postgis/postgis:18-3.6
    restart: unless-stopped
    environment:
      - POSTGRES_DB=db
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - ./pg_data:/var/lib/postgresql/data
```

--------------------------------

### Martin Source Code Breakpoint Location

Source: https://maplibre.org/martin/getting-involved

Example of the Martin entry point where a breakpoint can be set for debugging.

```rust
use clap::Parser;
use tracing::{error, info};
use martin::args::{Args, OsEnv};
use martin::srv::new_server;
use martin::{read_config, Config, MartinResult};

const VERSION: &str = env!("CARGO_PKG_VERSION");

async fn start(args: Args) -> MartinResult<()> {
    info!("Starting Martin v{VERSION}");
```

--------------------------------

### GET /{sources}

Source: https://maplibre.org/martin/sources-composite

Retrieves the TileJSON metadata for a composite source consisting of multiple comma-separated source names.

```APIDOC
## GET /{sources}

### Description
Retrieves the TileJSON configuration for a composite source, which combines multiple individual sources into one.

### Method
GET

### Endpoint
/{sources}

### Parameters
#### Path Parameters
- **sources** (string) - Required - A comma-separated list of source names (e.g., source1,source2).

### Request Example
curl localhost:3000/points,lines
```

--------------------------------

### Run Martin with Docker

Source: https://maplibre.org/martin/installation

Deploy Martin using a Docker container with environment variables for database configuration and a mounted volume for the configuration file.

```bash
export PGPASSWORD=postgres  # secret!

docker run -p 3000:3000 \
           -e PGPASSWORD \
           -e DATABASE_URL=postgres://user@host:port/db \
           -v /path/to/config/dir:/config \
           ghcr.io/maplibre/martin:1.13.0 \
           --config /config/config.yaml
```

--------------------------------

### Martin CLI Help Output

Source: https://maplibre.org/martin/run-with-cli

Displays the full list of available command-line arguments and options for the Martin server.

```text
Blazing fast and lightweight tile server with PostGIS, MBTiles, and PMTiles support

Usage: martin [OPTIONS] [CONNECTION]...

Arguments:
  [CONNECTION]...
          Connection strings, e.g. postgres://... or /path/to/files

Options:
  -c, --config <CONFIG>
          Path to config file. If set, no tile source-related parameters are allowed

      --save-config <SAVE_CONFIG>
          Save resulting config to a file or use "-" to print to stdout. By default, only print if sources are auto-detected

  -C, --cache-size <CACHE_SIZE>
          Main cache size (in MB)

  -s, --sprite <SPRITE>
          Export a directory with SVG files as a sprite source. Can be specified multiple times

  -f, --font <FONT>
          Export a font file or a directory with font files as a font source (recursive). Can be specified multiple times

  -S, --style <STYLE>
          Export a style file or a directory with style files as a style source (recursive). Can be specified multiple times

  -k, --keep-alive <KEEP_ALIVE>
          Connection keep alive timeout. [DEFAULT: 75]

  -l, --listen-addresses <LISTEN_ADDRESSES>
          The socket address to bind. [DEFAULT: 0.0.0.0:3000]

      --base-path <BASE_PATH>
          Set TileJSON URL path prefix.

          This overrides the default of respecting the X-Rewrite-URL header. Only modifies the JSON (TileJSON) returned, martins' API-URLs remain unchanged. If you need to rewrite URLs, please use a reverse proxy. Must begin with a /.

          Examples: /, /tiles

  -W, --workers <WORKERS>
          Number of web server workers

      --preferred-encoding <PREFERRED_ENCODING>
          Martin server preferred tile encoding. [DEFAULT: gzip]

          If the client accepts multiple compression formats, and the tile source is not pre-compressed, which compression should be used. gzip is faster, but brotli is smaller, and may be faster with caching.

          [possible values: brotli, gzip]

  -u, --webui <WEB_UI>
          Control Martin web UI. [DEFAULT: disabled]

          Possible values:
          - disable:        Disable Web UI interface. This is the default, but once implemented, the default will be enabled for localhost.
          - enable-for-all: Enable Web UI interface on all connections

  -b, --auto-bounds <AUTO_BOUNDS>
          Specify how bounds should be computed for the spatial PG tables. [DEFAULT: quick]

          Possible values:
          - quick: Compute table geometry bounds, but abort if it takes longer than 5 seconds
          - calc:  Compute table geometry bounds. The startup time may be significant. Make sure all GEO columns have indexes
          - skip:  Skip bounds calculation. The bounds will be set to the whole world

      --ca-root-file <CA_ROOT_FILE>
          Loads trusted root certificates from a file. The file should contain a sequence of PEM-formatted CA certificates

  -d, --default-srid <DEFAULT_SRID>
          If a spatial PG table has SRID 0, then this default SRID will be used as a fallback

  -p, --pool-size <POOL_SIZE>
          Maximum Postgres connections pool size [DEFAULT: 20]

  -m, --max-feature-count <MAX_FEATURE_COUNT>
          Limit the number of geo features per tile.

          If the source table has more features than set here, they will not be included in the tile and the result will look "cut off"/incomplete. This feature allows to put a maximum latency bound on tiles with extreme amount of detail at the cost of
          not returning all data. It is sensible to set this limit if you have user generated/untrusted geodata, e.g. a lot of data points at Null Island.

          Can be either a positive integer or unlimited if omitted.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Use RUST_LOG environment variable to control logging level, e.g. RUST_LOG=debug or RUST_LOG=martin=debug. See https://docs.rs/env_logger/latest/env_logger/index.html#enabling-logging for more information.
```

--------------------------------

### Enable Apache modules

Source: https://maplibre.org/martin/run-with-apache

Required modules for proxying and header manipulation.

```bash
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod headers
sudo a2enmod rewrite
```

--------------------------------

### Configure Martin with Environment Variables

Source: https://maplibre.org/martin/pg-ssl-certificates

Sets the root certificate path and database URL as environment variables before running Martin.

```bash
export PGSSLROOTCERT=./ca-cert.pem
export DATABASE_URL="postgres://postgres:password@localhost:5432/postgres?sslmode=verify-full"
martin
```

--------------------------------

### Restart Apache

Source: https://maplibre.org/martin/run-with-apache

Apply the new configuration by restarting the service.

```bash
sudo systemctl restart apache2
```

--------------------------------

### Martin CLI Debug Command

Source: https://maplibre.org/martin/getting-involved

Example command used for debugging Martin with a specific PostgreSQL connection string.

```bash
martin postgres://postgres:postgres@localhost:5411/db
```

--------------------------------

### GET /style/<style_id>/{z}/{x}/{y}.{filetype}

Source: https://maplibre.org/martin/sources-styles/rendering

Retrieves a rasterized image for an XYZ tile of a given style.

```APIDOC
## GET /style/<style_id>/{z}/{x}/{y}.{filetype}

### Description
Generates and returns a rasterized image (png or jpeg) for a specific XYZ tile of a given style.

### Method
GET

### Endpoint
/style/<style_id>/{z}/{x}/{y}.{filetype}

### Parameters
#### Path Parameters
- **style_id** (string) - Required - The identifier of the style to render.
- **z** (integer) - Required - The zoom level.
- **x** (integer) - Required - The x coordinate.
- **y** (integer) - Required - The y coordinate.
- **filetype** (string) - Required - The output format, e.g., png or jpeg.
```

--------------------------------

### GET /sprite/<sprite_id>.json

Source: https://maplibre.org/martin/sources-sprites

Retrieves the metadata index describing the position and size of each image inside the sprite.

```APIDOC
## GET /sprite/<sprite_id>.json

### Description
Retrieves the metadata index describing the position and size of each image inside the sprite. High-DPI versions are available by appending @2x.

### Method
GET

### Endpoint
/sprite/<sprite_id>.json
/sprite/<sprite_id>@2x.json

### Parameters
#### Path Parameters
- **sprite_id** (string) - Required - The identifier of the sprite source directory.
```

--------------------------------

### GET /{sources}/{z}/{x}/{y}

Source: https://maplibre.org/martin/sources-composite

Retrieves a vector tile for a composite source at the specified zoom level and coordinates.

```APIDOC
## GET /{sources}/{z}/{x}/{y}

### Description
Fetches a tile from a composite source, where each individual source is accessible via its name as a source-layer property.

### Method
GET

### Endpoint
/{sources}/{z}/{x}/{y}

### Parameters
#### Path Parameters
- **sources** (string) - Required - A comma-separated list of source names.
- **z** (integer) - Required - Zoom level.
- **x** (integer) - Required - X coordinate.
- **y** (integer) - Required - Y coordinate.

### Request Example
curl localhost:3000/points,lines/0/0/0
```

--------------------------------

### Configure Martin via CLI

Source: https://maplibre.org/martin/pg-ssl-certificates

Passes the CA root file and connection string directly as command-line arguments.

```bash
martin --ca-root-file ./ca-cert.pem \
      "postgres://postgres:password@localhost:5432/postgres?sslmode=verify-full"
```

--------------------------------

### Verify Apache configuration

Source: https://maplibre.org/martin/run-with-apache

Check for syntax errors before applying changes.

```bash
sudo apache2ctl configtest
```

--------------------------------

### GeoJSON Overlay FeatureCollection

Source: https://maplibre.org/martin/sources-styles/rendering

Example of a GeoJSON body for a POST request to render custom features on top of the base map.

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "LineString",
        "coordinates": [[-10, 5], [10, 5]] },
      "properties": { "line-color": "#f00", "line-width": 3, "line-cap": "round" }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [0, 0] },
      "properties": { "circle-color": "#00f", "circle-radius": 8 }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Polygon",
        "coordinates": [[[-5,-5],[5,-5],[5,5],[-5,5],[-5,-5]]] },
      "properties": { "fill-color": "#0a0", "fill-opacity": 0.5 }
    }
  ]
}
```

--------------------------------

### Expose Local Files to Martin

Source: https://maplibre.org/martin/run-with-docker

Mounts a local directory into the container and optionally enables the web UI via CLI flags.

```bash
docker run \
  -p 3000:3000 \
  -v /path/to/local/files:/files \
  ghcr.io/maplibre/martin:1.13.0 \
  /files
```

```bash
docker run \
  -p 3000:3000 \
  -v /path/to/local/files:/files \
  ghcr.io/maplibre/martin:1.13.0 \
  --webui enable-for-all \
  /files
```

--------------------------------

### Test SSL Connection with psql

Source: https://maplibre.org/martin/pg-ssl-certificates

Verifies the SSL connection by setting the root certificate path and using verify-full mode.

```bash
export PGSSLROOTCERT=ca-cert.pem
psql "postgres://postgres:password@localhost:5432/postgres?sslmode=verify-full"
```

--------------------------------

### Access JSON parameters in SQL

Source: https://maplibre.org/martin/sources-pg-functions

Example of using PostgreSQL JSON operators to extract values from the parsed query_params object.

```sql
...WHERE answer = (query_params->'objectParam'->>'answer')::int;
```

--------------------------------

### Retrieve Catalog

Source: https://maplibre.org/martin/using

List all available sources provided by the Martin server.

```bash
curl localhost:3000/catalog | jq
```

--------------------------------

### GET /sdf_sprite/<sprite_id>.(json|png)

Source: https://maplibre.org/martin/sources-sprites

Retrieves sprite indices or images formatted as Signed Distance Fields (SDFs) for runtime coloring.

```APIDOC
## GET /sdf_sprite/<sprite_id>.(json|png)

### Description
Retrieves sprite indices or images formatted as Signed Distance Fields (SDFs) for runtime coloring.

### Method
GET

### Endpoint
/sdf_sprite/<sprite_id>.json
/sdf_sprite/<sprite_id>.png

### Parameters
#### Path Parameters
- **sprite_id** (string) - Required - The identifier of the sprite source directory.
```

--------------------------------

### mbtiles meta-all

Source: https://maplibre.org/martin/mbtiles-meta

Prints all metadata values and tile detection results to stdout.

```APIDOC
## mbtiles meta-all

### Description
Outputs all metadata values and tile detection results. Note that the output format is not stable and is intended for visual inspection.

### Usage
`mbtiles meta-all <file_path>`
```

--------------------------------

### General Development Workflow Commands

Source: https://maplibre.org/martin/development

Standard commands for managing the test database, server, and code quality.

```bash
just start       # start test database
just run         # start Martin server
just test        # run all tests
just fmt         # format code
just clippy      # lint code
just docs        # serve documentation preview
just stop        # stop test database
```

--------------------------------

### Initialize MVTLayer and DeckGL

Source: https://maplibre.org/martin/using-with-deck-gl

Configures an MVTLayer with a data source and initializes the DeckGL instance with a map style and initial view state.

```javascript
const pointsLayer = new MVTLayer({
  data: 'http://localhost:3000/points',
  pointRadiusUnits: 'pixels',
  getRadius: 5,
  getFillColor: [230, 0, 0]
});

const deckgl = new DeckGL({
  container: 'map',
  mapStyle: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
  initialViewState: {
    latitude: 0,
    longitude: 0,
    zoom: 1
  },
  layers: [pointsLayer]
});
```

--------------------------------

### Print all metadata values

Source: https://maplibre.org/martin/mbtiles-meta

Outputs all metadata and tile detection results to stdout for visual inspection.

```bash
mbtiles meta-all my_file.mbtiles
```

--------------------------------

### GET /function_zxy_query/{z}/{x}/{y}

Source: https://maplibre.org/martin/sources-pg-functions

Invokes a PostgreSQL function to return an MVT tile, supporting optional query parameters passed as a JSON object.

```APIDOC
## GET /function_zxy_query/{z}/{x}/{y}

### Description
Invokes a PostgreSQL function that returns an MVT tile. Query parameters can be passed via the URL to filter or modify the function output.

### Method
GET

### Endpoint
/function_zxy_query/{z}/{x}/{y}

### Parameters
#### Path Parameters
- **z** (integer) - Required - The zoom level of the tile.
- **x** (integer) - Required - The x coordinate of the tile.
- **y** (integer) - Required - The y coordinate of the tile.

#### Query Parameters
- **query_params** (json) - Optional - Additional parameters passed to the function, which can be accessed within the SQL using JSON operators.
```

--------------------------------

### GET /sprite/<sprite_id>.png

Source: https://maplibre.org/martin/sources-sprites

Retrieves the combined PNG sprite image for a given sprite ID. High-DPI versions are available by appending @2x.

```APIDOC
## GET /sprite/<sprite_id>.png

### Description
Retrieves the combined PNG sprite image for a given sprite ID. High-DPI versions are available by appending @2x.

### Method
GET

### Endpoint
/sprite/<sprite_id>.png
/sprite/<sprite_id>@2x.png

### Parameters
#### Path Parameters
- **sprite_id** (string) - Required - The identifier of the sprite source directory.
```

--------------------------------

### Running Tests with PostgreSQL Dependencies

Source: https://maplibre.org/martin/development

Commands to execute tests based on whether they require a live PostgreSQL connection.

```bash
# Run tests that don't require PostgreSQL (no external dependencies)
just test-cargo

# Run all tests including PostgreSQL tests (requires PostgreSQL running)
just test     # runs all tests
just test-pg  # starts PostgreSQL and runs only PostgreSQL-requiring tests
```

--------------------------------

### Debug PostgreSQL SSL Connections

Source: https://maplibre.org/martin/pg-ssl-certificates

Use these environment variables and commands to enable verbose logging for psql and Martin when troubleshooting SSL handshake or connection issues.

```bash
export PGSSLMODE=verify-full
export PGSSLROOTCERT=./ca-cert.pem
# Verbose psql
psql -h localhost -U postgres -d postgres -v

# Debug Martin
RUST_LOG=debug RUST_LOG_FORMAT=pretty martin postgres://...
```
Tokens:
Raw